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

Annotations only say readOnly=false, destructive=false, idempotent=false; the description adds genuinely new behavioral facts: that set_update_set *binds* subsequent writes to an update set, and that script/atf/set_update_set gate on confirm=true. That is real disclosure beyond the structured fields. It stops short of describing side effects or scope of a server-side script, holding 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?

A single front-loaded paragraph enumerating actions with minimal filler; the parenthetical confirm notes are terse and earn their place. It could be tightened by grouping the three confirm-requiring actions instead of repeating the phrase.

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 an eight-parameter, eight-action tool with zero schema descriptions, the description leaves too much undocumented — an agent cannot tell what 'text', 'suite', 'group', or 'limit' apply to for a given action. The output schema covers return values, but per-action parameter mapping is the critical missing piece.

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 0% across eight parameters, so the description carries the full burden and only partially delivers: it implies script/update_set usage per action and documents confirm, but text, group, limit, suite, and the interaction between action and its inputs are never explained.

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?

It frames the tool as an 'administrative surfaces' dispatcher and enumerates the eight actions, with verbs supplied for three of them (set_update_set 'bind writes', script 'run a server-side script', atf 'run tests'). But users/groups/roles/memberships are bare nouns with no stated effect, and nothing distinguishes this from siblings like sn_write or sn_code that plausibly overlap.

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 states confirm=true is required for three mutating actions, which is a useful precondition, but there is no guidance on when to pick this tool over sn_read (for listing users/groups) or sn_code (for running scripts). An agent has to infer the routing decision entirely.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds that results are computed without pulling records, which is useful, but says nothing about cost, limits, or empty-result behavior beyond what annotations and the output schema convey.

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 waste, the action modes front-loaded and the value proposition last. Efficient and scannable.

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?

Output schema and annotations carry return shape and safety, and the description covers the core action modes, but with 6 undocumented params and 0% coverage the agent lacks guidance on query/table formats and the two-level grouping.

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 0% across 6 params, so the description must compensate. It clarifies the action enum and the aggregate values (COUNT/SUM/AVG/MIN/MAX) and hints at group_by semantics, but leaves query, table, group_by_2, and the relationship between the two group fields entirely undocumented.

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

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

States a specific verb+resource ('Aggregate over a table') and enumerates the two action modes (stats vs group) with the aggregates supported. It's clearly distinguishable from a record-fetching sibling like sn_read via the 'without pulling records' framing, though it never names an alternative.

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 call answers how many / how many per group without pulling records' implies usage versus record retrieval but doesn't explicitly say when to prefer this over sn_read or other siblings, nor any exclusions. Usage is inferable rather than stated.

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=false, destructiveHint=false, so the safety profile is partly covered. The description adds one genuinely useful behavioral fact beyond the annotations: order submission is gated on confirm=true. It does not say what turns non-idempotent, whether orders are reversible, or what auth is needed.

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 compact sentence that front-loads the resource then lists modes telegraphically. Nothing is wasted, but the compression crosses into ambiguity in places (e.g. 'action=variables (an item's form fields)' does not read cleanly).

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 an 8-parameter, mutation-capable, multi-mode catalog tool with zero schema descriptions, the description is thin: it leaves the mapping from parameters to actions unexplained and gives no guidance on paging (limit) or text search. The presence of an output schema removes the need to describe returns, but the invocation gaps remain large.

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% across 8 parameters, so the description must carry the whole burden. It only explains 'action' and 'confirm'; item, text, limit, category, quantity, and variables are never mentioned, including which action consumes item vs category vs variables.

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?

Identifies the resource (Service Catalog) and enumerates the four modes with a short gloss for each (browse, an item's form fields, submit an order). An agent can tell what each action does, though it cannot tell this tool apart from siblings like sn_read or sn_write, which also touch ServiceNow records.

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 action enumeration implicitly routes mode selection, and 'action=order ... needs confirm=true' is an explicit precondition for the risky mode. But there is no statement of when to use this versus sn_read/sn_write/sn_aggregate, and no exclusion guidance anywhere.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail about how where_used scoping narrows the search surface, but says nothing about limits, result truncation, or the cost of broad searches.

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

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

A single dense sentence, front-loaded with the purpose before the action breakdown. The nested parentheses are slightly heavy but every clause carries real 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. But for an 8-parameter, 0%-coverage multi-action tool, the missing parameter-to-action mapping is a real gap that would cause wrong invocations.

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 0%, so the description must carry the load. It explains the action enum and the scope values well, but leaves name, text, limit, table, sys_id, and artefact undocumented, and never maps which parameter belongs to which action (e.g. read needs sys_id vs name).

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 ('Find') and resource ('the instance's own automation'), then enumerates all four actions with parenthetical meanings, so an agent knows what the tool does. It does not distinguish itself from siblings like sn_read or sn_schema, which prevents a 5.

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

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

The per-action glosses imply when each action applies (search vs list vs read vs where_used), and the scope semantics ('code'/'schema'/empty) are useful. However, there is no explicit guidance on when to use sn_code instead of the sibling tools, so the agent must infer the boundary.

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 confirm-flag requirement for upload and delete adds real safety context. But the description openly advertises a delete action while annotations declare destructiveHint=false, giving the agent a conflicting signal about whether this tool can remove data irreversibly. It also says nothing about permissions, size limits, or what upload/download return despite no annotation coverage for those traits.

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 compact sentence that front-loads the resource and then maps each action, with the critical confirm constraint attached to the right actions. No filler, though the extremely telegraphic style ('Record attachments.') costs a little clarity.

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 mutating, 6-parameter tool with zero schema documentation, the description is too thin: it omits how name/table/sys_id/content_base64 interact per action and how download content is returned. An output schema exists, which relieves some burden, but the per-action parameter contract is still 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 0% across 6 parameters, so the description must compensate and it largely does not. It explains action and confirm semantics well, but name, table, sys_id, and content_base64 are left entirely undocumented in both schema and description – an agent cannot tell, for example, whether sys_id is the record ID or the attachment ID.

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 resource (attachments on records) and enumerates the four supported operations (list, download, upload, delete) with their action values, which maps directly onto the action enum. It does not explicitly differentiate itself from siblings like sn_read or sn_write, but the resource is specific enough that an agent knows this is the attachment tool.

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

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

It does state per-action preconditions (upload and delete need confirm=true), which is useful usage information. However, it gives no guidance on when to prefer this tool over the sibling tools, no exclusivity rules, and no explanation of when each action is appropriate beyond the enum names themselves.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not disclose traversal cost, truncation behavior at the default limit of 200, or what 'depth' actually does when walking the graph.

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

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

A single dense sentence with the resource front-loaded and the five modes packed in parentheses. Every clause carries information; nothing is redundant or restated 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?

An output schema exists, so return values need not be described, and annotations cover safety. But for an 8-parameter graph traversal tool with zero schema descriptions, the definition leaves key operational questions (how deep is safe, what gets truncated, what identifiers go in sys_id vs target vs model) unanswered.

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% for 8 parameters, so the description carries the burden. It does add genuine meaning for 'action' (glossing each enum value beyond the bare names) and hints at 'kind' via 'a table, field or script'. However depth, limit, model, sys_id, target and direction are left completely unexplained.

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

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

The description names a specific resource (CMDB Service Graph) and enumerates five concrete query modes with plain-language glosses, e.g. 'dependents (what breaks if this CI goes away)'. An agent can tell it is a read/query tool for graph relationships, though nothing distinguishes it from the schema-oriented sibling sn_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?

The action list implicitly tells the agent which mode corresponds to which question, which is more than most tools offer. But there is no explicit when-to-use-this-vs-sn_schema/sn_aggregate guidance, no prerequisites (e.g. must a sys_id exist first), and no 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 destructiveHint=true, readOnlyHint=false and non-idempotence; the description corroborates this by warning that undo 'changes the instance' and adds the useful detail that confirm=true is required. It does not disclose scope of the revert (single entry only?), whether the undo itself is journaled or reversible, or any permission requirements.

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

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

Two compact sentences, no filler, with the destructive warning about undo placed inline where it matters. Every clause carries information an agent needs before invoking either mode.

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 values needn't be described. But for a destructive 4-parameter tool with 0% schema description coverage, the definition never explains how to target a specific journal entry for undo, nor which parameters apply to which action — a real gap for the mutation 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?

Schema description coverage is 0%, so the description must carry parameter meaning, and it only explains action and confirm. The limit and entry_id parameters are never mentioned — critically, nothing says that entry_id identifies which write undo reverts, leaving the undo path underspecified despite a 4-parameter schema.

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

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

States a specific resource (the write journal) and names both operating modes with their effects, so an agent can distinguish listing applied writes from reverting one. It does not contrast itself against siblings like sn_write or sn_admin, which is the only missing piece.

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 two actions are explained with the condition that undo requires confirm=true and mutates the instance, which gives implied guidance on which mode to pick. However there is no explicit statement of when to reach for this tool versus sn_write to inspect or change writes, and no guidance on prerequisites for journal mode.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered externally. The description adds almost nothing beyond listing action names — no note about what 'history' or 'cache' contain, whether saved_run executes arbitrary stored queries, or any limits/scope of results.

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?

It is short and front-loaded, but the action list is a flat comma-separated run-on with only two parenthetical hints. No wasted prose, yet the structure does not help the agent parse per-action behavior.

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 tool with eight actions, seven parameters, and no per-parameter documentation, the description is far too thin to support correct invocation — the agent cannot know, for example, that saved_run likely needs a name and note_read likely needs a key. The presence of an output schema excuses return-value detail, but not the action/parameter contract.

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% across seven parameters (key, body, name, limit, table, sys_id), and the description provides no mapping of which parameter applies to which action. The action enum values are already fully listed in the schema, so the description adds essentially no semantic content beyond structured data.

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 lead sentence 'Read what the server already knows' combined with the action list conveys a read-only knowledge-retrieval tool with eight sub-operations. However, it never distinguishes itself from read-oriented siblings like sn_read, sn_state, or sn_journal, so an agent cannot tell which namespace of 'knowledge' this covers without guessing.

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 when-to-use or when-not-to-use guidance is given, and no sibling is named as an alternative. An agent facing sn_read, sn_state, sn_journal, and sn_knowledge has no basis in the description for choosing among them.

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 state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that, notably that properties are returned with secrets masked, and it characterizes what health, jobs, and stats provide.

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

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

The description is a single compact sentence, front-loads the resource, and then enumerates actions efficiently with no filler. Every clause maps to a supported action.

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 tool has an output schema, so return values need not be detailed, and annotations cover safety. However, for a multi-action tool with four params and 0% schema descriptions, the definition should explain level, limit, and source, and should give some sibling-routing 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?

Schema description coverage is 0%, so the description must explain the four parameters. It explains all five action enum meanings, but it leaves level, limit, and source completely undocumented, meaning most parameters remain semantically opaque.

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 clear resource ("Instance operations") and enumerates the five concrete actions it supports, so an agent can infer it is an operational/diagnostic query tool. It does not differentiate itself from siblings such as sn_admin, sn_state, or sn_journal, which keeps it below a 5.

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

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

It lists action values, which helps choose the action parameter, but it gives no guidance on when to use this tool versus the many sibling tools, and no exclusions or prerequisites. The internal action list is useful but does not substitute for tool-selection 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the mode-switching model but says nothing about pagination, default limit of 100, or the effect of display_value — all behaviors an agent would want 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 short sentences, front-loaded with the purpose, then the action taxonomy, then a consolidation rationale. Nothing is redundant and the final sentence earns its place by telling the agent this replaces per-table tools.

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 means return values needn't be explained, but a nine-parameter generic read tool needs pagination semantics (limit/offset), field selection, ordering and display_value called out. With 0% schema coverage and no such guidance, the description is too thin for the tool's surface area.

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% across nine parameters, so the description carries the full burden — yet it only explains the three action enum values and gestures at query ("encoded query") and sys_id. limit, offset, fields, order_by, table and display_value are left entirely undocumented anywhere.

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

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

States a specific verb+resource ("Read ServiceNow records") and enumerates the three action modes with concrete meaning for each. It doesn't differentiate against the closest sibling, sn_aggregate, which plausibly overlaps on the count case, but the core purpose is 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?

Gives clear in-tool selection guidance — query to list, get for one record by sys_id, count for the total — which is the main ambiguity an agent faces here. It stops short of saying when to prefer sn_aggregate or sn_write, and offers no 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, idempotentHint and destructiveHint=false, so safety is fully covered by structured data; 'introspect' is consistent with that. The description adds nothing beyond the annotation about result size, pagination/limit behavior, or whether introspection reflects cached vs live metadata.

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 with the core purpose first, followed by a compact action cheat-sheet. No filler; every clause carries an action 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?

Given an output schema exists (return values need not be described), read-only annotations covering safety, and an action dispatch model fully enumerated, the description supplies enough for an agent to pick the right mode. Remaining param-to-action binding gaps are the only shortfall.

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% across 5 parameters, so the description must compensate. It usefully maps the four action enum values to behaviors, but leaves name, table, pattern, and limit unlinked to specific actions (e.g., which action consumes 'pattern', or that 'limit' caps table listing), leaving real ambiguity.

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: 'Introspect the instance's data model', which distinguishes metadata exploration from the data-access siblings like sn_read. It then enumerates the four modes of introspection, so the agent can tell what the tool covers without opening the schema.

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

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

The action list implies when each mode is used (tables to list, fields for a dictionary, class for CMDB, references for field usage), but there is no explicit when-to-use, when-not-to-use, or routing to siblings such as sn_read or sn_admin for overlapping lookups.

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=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.

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds valuable behavioral context beyond those annotations: every write requires confirm=true, writes are journalled, and they can be reverted. It does not detail per-action effects or auth requirements, but it substantially improves the safety profile.

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 tightly written sentences with no wasted text. The core purpose is front-loaded, followed immediately by action meanings and the confirm/journaling safety rule.

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 values need not be explained. Annotations cover the destructive safety profile and the description adds the confirm/journaling workflow, but for a six-parameter write tool with 0% schema description coverage, the missing action-specific parameter guidance leaves the definition only partially complete.

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

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

Schema description coverage is 0% across six parameters, so the description must compensate. It explains action values and the confirm requirement, plus that batch applies many operations in one request, but it says nothing about table, fields, sys_id, or the structure of operations, leaving most parameter semantics undocumented.

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 a specific verb and resource: "Change ServiceNow records," and enumerates the supported write actions. It distinguishes this from read-oriented siblings implicitly through the write/change framing, but does not explicitly name an alternative tool.

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

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

The description implies this is the tool for writes by enumerating create/update/delete/batch and notes that batch is for many operations in one request. However, it gives no explicit when-not-to-use guidance or comparison to siblings such as sn_read or sn_journal.

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