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

Annotations already mark readOnlyHint=true, and the description adds useful behavioral context: computation happens server-side, uses the Stats API, supports grouping, and avoids downloading rows. This meaningfully extends the structured metadata 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?

Two sentences, front-loaded with the core purpose, and no redundant words. The efficiency cue 'Avoids pulling individual rows' earns its place by informing agent decision-making.

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 10-parameter tool with no output schema, the description covers the essential behavioral contract: what it computes, how it computes it, and why it is preferable to row-level queries. The main gap is not spelling out the return shape, but annotations and schema coverage reduce the burden considerably.

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 input schema already documents all 10 parameters. The description adds only the high-level concept of 'optional grouping', which is consistent with group_by and having but does not deepen parameter-level meaning beyond what the schema provides.

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 ('Compute'), a clear resource ('a table'), and the exact operations ('count, avg, min, max, sum') via the Stats API. 'Avoids pulling individual rows' distinguishes it from row-returning sibling tools like servicenow_query_table.

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 clearly implies when to use this tool: when server-side aggregates are needed instead of fetching individual rows. It does not name the alternative explicitly or list exclusion conditions, but the context is strong enough for an agent to route 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?

Annotations already mark the tool as read-only and open-world, and the description adds useful behavioral context: it reports achievable capabilities and warns that reads may be silently empty in restricted environments. It does not describe exact output structure, but the warning adds meaningful transparency.

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, front-loads the purpose, and adds a concrete usage warning. Every sentence contributes useful information without fluff 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?

For a simple read-only preflight tool with one optional parameter, annotations, and a clear description, the definition is complete. It states what it checks, when to use it, and the key risk it mitigates, so an agent can select and invoke 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?

The only parameter, 'instance', is fully described in the schema as the connection profile with a default and a pointer to servicenow_list_instances. With 100% schema coverage, the description doesn't need to add parameter details, so the baseline score of 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 opens with a specific verb ('Preflight') and names the concrete resource (admin-restricted sys_* tables) plus the higher-level capabilities being checked. This clearly distinguishes the tool from record/query/attachment siblings, which perform different operations.

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 says to run this before relying on scripts/flows/codecheck tools on a governed instance, and warns about silently empty reads on least-privilege accounts. This gives clear contextual guidance, though it does not explicitly list when NOT to use the tool.

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?

There are no annotations, so the description carries the disclosure burden. It says a record is created but does not mention that the default plan mode can return a non-mutating preview unless 'apply' is true, nor does it disclose side effects or write-mode 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?

A short, front-loaded single sentence with no filler. Every word earns its place, and the core operation is stated immediately.

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

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

No output schema exists, and the description does not explain return behavior, the apply/preview default, or error conditions. For a mutation tool with a notable 'apply' nuance, this is too sparse to fully enable a correct call.

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 input schema fully documents 'table', 'fields', and 'apply'. The description adds little beyond the phrase 'given field values', which loosely maps to the 'fields' parameter without providing extra semantic value.

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 ('Create') and a clear resource ('a new record in a table with the given field values'). It is unambiguous and distinguishes itself from siblings like servicenow_update_record, servicenow_query_table, and servicenow_delete_record.

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

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

No guidance is given on when to choose this tool over alternatives, prerequisites, or conditions such as write mode or an existing table. The only usage signal is the verb itself, which implies the purpose but does not explicitly route the agent.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It only says 'Delete' and does not mention irreversibility, permissions, or the plan-mode preview behavior described in the apply parameter.

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 sentence with no filler, front-loading the action and target. It is appropriately sized for the minimal information it conveys.

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 mutation with no annotations and no output schema, the description is too sparse. It misses prerequisites, side effects, and execution-mode caveats; only the schema's apply and instance fields partially fill this gap.

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

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

All three parameters have meaningful descriptions in the schema, so the baseline is 3. The description's 'by its sys_id' adds little beyond what the schema already states for attachment_sys_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 states the exact operation (delete), the resource (attachment), and the selection method (by sys_id). This is clearly distinct from sibling tools like servicenow_delete_record and the other attachment-related operations.

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 no guidance on when to use this tool versus alternatives, nor does it mention how to obtain the required sys_id. It relies on the schema for context but provides no exclusion or alternative references.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention that deletion may be irreversible, that permissions are required, or the plan-mode nuance where omitting apply returns a non-mutating preview. The schema's apply parameter hints at this, but the description itself adds no behavioral context.

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, efficient, front-loaded sentence with no filler. However, it is very sparse and leaves out important caveats like the plan-mode behavior, so while it is concise, it is not as informative as a top-tier description could be.

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 schema is rich and documents apply and instance, which helps an agent understand the mechanics. But with no annotations and no output schema, the description leaves out the destructive/preview caveat and does not clarify what response or side effects to expect. It is minimally adequate but has clear 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 schema already provides high-coverage descriptions for all four parameters (apply, table, sys_id, instance), so the baseline is 3. The description only mentions sys_id in passing and adds no meaning about table names, the apply flag, or connection profiles beyond what the schema states.

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 (Delete), targets a concrete resource (a record in a ServiceNow table), and identifies the lookup key (sys_id). This clearly distinguishes it from sibling tools such as servicenow_get_record, servicenow_update_record, and servicenow_delete_attachment.

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?

There is no guidance about when to use this tool versus alternatives, no exclusions, and no mention of cases where a non-destructive operation or an attachment deletion would be more appropriate. The intended usage is only implied by the tool name and title.

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, so the read-only nature is covered. The description adds useful behavioral context by naming the exact source table and the fields returned, but it does not describe error behavior, instance resolution, or any external network implications despite openWorldHint=true.

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

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

A single sentence that front-loads the action and resource, then compacts the output fields into a parenthetical list. There is no filler or redundant phrasing.

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

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

For a simple read-only describe operation with one required parameter, the description provides sufficient context: what it lists, where it reads from, and which columns are returned. The absence of an output schema is mitigated by the explicit field list in the description.

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

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

Schema description coverage is 100%, with both 'table' and 'instance' clearly described. The description adds mild context by clarifying that the output comes from sys_dictionary, but the parameters themselves are already well documented in the schema, so the baseline of 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 uses a specific verb ('List') and resource ('a table's columns') and identifies the data source ('from sys_dictionary'). It clearly distinguishes this tool from siblings like servicenow_list_instances or servicenow_get_status, which serve different purposes.

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 the tool: when you need table column metadata from sys_dictionary. It does not explicitly state when-not-to-use or name alternative tools for related tasks, but the sibling context makes the intended use reasonably clear.

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, but the description adds valuable behavioral detail: the output is base64 and large files will be refused referencing SN_MAX_RESULT_CHARS. This goes beyond what annotations provide and sets clear expectations for the agent.

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 extremely concise, using two short sentences. The primary action and output format are front-loaded, and the key limitation is stated without ambiguity. Every word contributes to understanding.

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 download operation with only one required parameter and no output schema, the description covers all essential aspects: what it does, the return format, and a critical size limitation. No additional context is needed for an agent to invoke 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?

The input schema provides complete descriptions for both parameters (instance and attachment_sys_id), so the description does not need to add param-level detail. It does indirectly reference a size constraint via SN_MAX_RESULT_CHARS, but this is not tied to a specific parameter. This aligns with the baseline for high schema coverage.

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 action ('Download') on a specific resource ('an attachment's bytes') and specifies the return format ('base64'). This distinguishes it from sibling tools like credential management or instance listing, making its purpose 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 provides clear context for when the tool is appropriate (downloading attachments) and includes a critical limitation ('Large files are refused') that guides usage. It does not explicitly name alternatives, but no direct alternative exists among the listed siblings, so this 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=true and openWorldHint=true, and the description does not contradict them. It adds useful scope ('single attachment', 'metadata'), but it does not disclose output shape or any edge-case 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?

One sentence with the action and object front-loaded and no filler. Every word contributes to the 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?

For a simple read-only, two-parameter tool, the description plus schema and annotations cover what an agent needs to invoke it. There is no output schema, but 'metadata' conveys the return type at a useful level; more detail about returned fields would be a minor enhancement.

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 provides complete descriptions for both parameters, including a reference to servicenow_list_instances for the instance parameter. The tool description echoes 'by its sys_id' but adds no significant meaning beyond the schema.

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

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

States a specific verb 'Read', a specific resource 'a single attachment's metadata', and the method 'by its sys_id'. This clearly differentiates it from sibling tools, which are about instance management, status, and connection testing.

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 clearly implies the prerequisite: you must have an attachment_sys_id and want metadata for one attachment. It does not explicitly name alternatives or exclusions, but none of the listed sibling tools perform attachment operations.

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 no annotations present, the description carries the full burden of behavioral disclosure. It states the operation is a read, but does not describe the response format, behavior for missing records, required permissions, or any other runtime behavior beyond the core action.

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 focused sentence that communicates the essential operation immediately. There is no redundant wording or 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?

The tool is simple and the schema covers parameters well, but there is no output schema and the description does not explain return conventions or error behavior. For a basic read operation this is close to sufficient, but some edge-context detail 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 input schema already documents all four parameters thoroughly, including examples and default behavior for fields and instance. The description adds no extra parameter detail, which is acceptable because schema coverage is effectively complete.

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 (Read), the resource (a single record from a table), and the key identifier (sys_id). It is distinct from sibling tools like servicenow_aggregate or servicenow_list_attachments, though it does not explicitly name any 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?

The description implies use when a specific sys_id is known and a single record is needed, but it provides no explicit guidance on when to use this tool versus siblings such as servicenow_get_attachment or servicenow_aggregate.

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 adds a meaningful behavioral trait beyond the readOnlyHint annotation: explicitly stating that the password is never revealed. It also clarifies the scope of output (configuration and credential completeness, not secrets), which is valuable for an agent deciding whether to call this 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?

Two short sentences with zero filler. The first sentence front-loads what is shown; the second preempts a likely security concern. Every word 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 read-only status tool with an output schema present and a single optional parameter documented in the schema, the description covers the essential behavioral and security context. It lacks nothing critical for an agent to use the tool correctly, though a touch more detail about how the optional instance parameter affects results could push it higher.

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% for the single optional parameter, with the schema already explaining that 'instance' selects a connection profile. The description adds no additional parameter-level detail, so the baseline of 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 uses a specific verb ('Show') and enumerates the exact resource and fields (configured instance, user, auth mode, access policy, credential completeness), making it unmistakably distinct from siblings like servicenow_query_table and servicenow_check_capabilities.

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 purpose implies when to use it (e.g., before other ServiceNow operations, to verify connection configuration), but it offers no explicit guidance about situations where a sibling would be better, nor does it name alternatives. The usage context is inferred 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 provide readOnlyHint=true, so the safe read behavior is covered. The description adds the useful distinction that only metadata is returned, not file content, and that scoping is optional. However, it discloses nothing about pagination, result size limits, or behavior when no scope is provided.

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 states the core purpose immediately and adds the scoping detail without fluff. Every word 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 read-only listing tool, the description, schema, and annotations together cover the essential who/what/where. It could be more explicit about whether table and sys_id are required together and whether listing without them returns all attachments, but the 'optionally scoped' phrasing and schema descriptions largely fill those 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?

All three parameters (table, sys_id, instance) have descriptive text in the schema, so the description adds no additional parameter meaning. With high schema coverage, a baseline of 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 ('attachment metadata'), and clarifies the optional scoping by table + sys_id. This clearly differentiates it from sibling upload/delete tools without ambiguity.

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 context about optional scoping but provides no guidance on when to use this tool versus alternatives like servicenow_upload_attachment or servicenow_delete_attachment. No exclusions or conditional routing are mentioned.

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 no mutation occurs, and the description adds meaningful behavioral context: passwords are explicitly never included, a read-only flag is returned, and credential completeness is reported. This valuable detail goes beyond what the annotations alone 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?

Two short sentences, with the primary purpose front-loaded and a security-relevant note appended without excess. Every clause earns its place, and there is no repetitive or boilerplate language.

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

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

For a simple, read-only listing tool with zero required parameters and no output schema, the description names all meaningful output fields and explicitly covers the password-exclusion guarantee. It is nearly complete, though a note about the return container or pagination would fully remove ambiguity for agents expecting an array shape.

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 only parameter, instance, is fully documented in the schema with its default behavior and a reference to this tool. The description itself does not add further parameter-level guidance, so the schema carries the burden and the baseline of 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 uses a specific verb ('List') and a clear resource ('configured ServiceNow connection profiles (instances)') and enumerates the returned fields: name, host, user, read-only flag, and credential completeness. This clearly distinguishes the tool from the inline-invocation siblings that check credentials or capabilities.

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 to inspect available connection profiles, and the parameter schema notes the active-profile default. However, it never explicitly states when to use this tool instead of the sibling tools, nor does it mention any exclusions or prerequisites for calling it.

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 description only needs to add context beyond that. It does add the specific source (sys_db_object) and the filtering behavior, but it does not disclose pagination, result shape, or the fact that unfiltered calls may return a large list. 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?

The description is a single sentence that front-loads the core action and resource, then adds the optional filtering detail. There is no filler or redundancy; every word 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 listing tool with two optional parameters, full schema coverage, and read-only annotations, the description is nearly complete. The only minor gap is the absence of any return-shape or pagination notes, but the tool name and 'list' verb strongly imply a table list, so this is not a significant omission.

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

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

Schema coverage is 100% — both parameters already have descriptions. The description adds semantic context for 'filter' by explaining it matches a fragment in name or label, which goes slightly beyond the schema's bare description. The 'instance' parameter is covered fully by the schema, so no further description 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?

The description states a specific verb ('List') and a concrete resource ('tables from sys_db_object'), and clearly distinguishes the metadata-listing purpose from sibling record-manipulation tools like servicenow_query_table and servicenow_get_record. The optional filter by name or label is also explicit.

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 conveys a clear context: use this tool to discover available ServiceNow tables from the system metadata table. It does not explicitly name alternatives or state when not to use it, but the sibling set makes the intended use obvious, and the mention of an optional filter implies its use for narrowing discovery.

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 and openWorldHint annotations already communicate that this is a safe read operation, which the description's 'Read records' wording confirms. The description adds some value by mentioning Table API support, encoded queries, field selection, and pagination, but it does not disclose behavior like response shape, server-side caps, or what happens with fetchAll. This is adequate given the annotations but not richly transparent.

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 tight sentences, front-loading the core purpose ('Read records from any ServiceNow table') and then summarizing the key capabilities without redundancy. No words are wasted, and 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?

For a tool with 9 parameters and no output schema, the description gives a useful high-level overview but leaves several contextual details to the schema, such as defaults, limits, and formatting options. It does not describe the return structure or differentiate from close siblings. It is sufficient but not complete enough to guide an agent without consulting the schema heavily.

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 input schema already documents all 9 parameters in detail with examples, defaults, and enums. The description's reference to 'encoded queries, field selection and pagination' maps to query, fields, and limit/offset/fetchAll, but it adds no meaning beyond what the schema already provides. A 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 clearly states the action ('Read records') and the resource ('any ServiceNow table through the Table API'), which identifies the tool's purpose. It does not explicitly differentiate from siblings like servicenow_get_record or servicenow_aggregate, but the combination of plural records, encoded queries, and pagination makes its query-oriented role reasonably clear.

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

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

The description implies when to use the tool through 'Supports encoded queries, field selection and pagination' and the phrase 'any ServiceNow table.' However, it does not explicitly say when not to use it or mention alternatives such as servicenow_get_record for single-record lookups or servicenow_aggregate for aggregate queries. The usage context is implied 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?

Beyond the idempotentHint annotation, the description discloses the practical side effect: values are persisted to the env file and affect all later requests. The 'provide any subset' clause also signals partial updates. This adds meaningful behavioral context not present in the annotations alone.

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 deliver purpose, persistence behavior, and the partial-update rule with no fluff. The most important 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?

For a simple configuration tool with four fully documented optional parameters and no output schema, the description covers purpose, side effects, and usage scope. Nothing essential is missing for an agent to invoke 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 each parameter is already well documented. The description adds only the global hint that any subset of fields can be provided, which is useful but does not deepen per-parameter semantics.

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 uses a specific verb-resource pair: 'Save or update the ServiceNow connection credentials.' It clearly distinguishes this configuration tool from the data-operation siblings by noting persistence and use across subsequent requests.

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: credentials are persisted to the env file and used for all subsequent requests, implying this should be called to configure the connection before other operations. It does not explicitly name alternatives or exclusion cases, but the intended use is unambiguous.

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 readOnlyHint annotation, the description adds valuable behavioral context: it reads exactly one sys_user record, and it explicitly states that auth and connectivity problems are returned structurally (ok:false) rather than as errors. This gives an agent accurate expectations about failure modes.

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 concise sentences with no wasted words. The primary purpose is front-loaded, and the error-handling caveat is placed second, which is natural and useful.

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

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

For a simple one-parameter tool with a readOnly annotation and an output schema, the description is nearly complete. It covers purpose, behavioral scope, and error semantics. The only missing piece is explicit differentiation from sibling tools, but that is a minor gap given the tool's simplicity.

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% for the single optional parameter, so the schema already handles parameter documentation. The tool description itself adds no parameter details, though the schema pointing to servicenow_list_instances is helpful. 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 clearly states the tool's purpose: verifying configured credentials by reading one sys_user record and reporting ok/status/latency. This distinct focus on credential verification differentiates it from siblings like get_status and check_capabilities, and includes a specific resource and behavior.

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 it ('verify that the configured credentials actually work'). However, it does not explicitly mention when not to use it or how it compares to sibling tools, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a mutating but non-destructive operation. The description adds no additional behavioral context, such as permissions, reversibility, or the preview/plan mode behavior encoded in the 'apply' parameter. It is consistent with annotations but adds little beyond them.

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, front-loaded sentence with no redundant words. It immediately names the action, target, and key identifier, making it efficient and easy to parse.

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 the rich schema (which covers parameters and the apply/preview behavior) and the annotations covering mutation safety, the concise description is sufficient for an agent to understand the tool's core purpose. It does not explain the preview mode, but that is fully documented in the apply parameter description, so nothing critical 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%, so the schema fully documents all five parameters, including table, sys_id, fields, and the apply flag. The description itself adds no parameter-level meaning, so a baseline score of 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 ('Update'), a resource ('fields on an existing record'), and the identifier ('sys_id'). This clearly distinguishes it from creating, deleting, querying, or fetching records, so an agent can select it without ambiguity.

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

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

The description implies the tool is for modifying existing records (as opposed to creating or deleting), but it does not explicitly mention alternatives or state when not to use it. No prerequisites or exclusions are given, so the guidance is adequate but not 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?

Annotations already signal that this is a mutating, non-destructive operation (readOnlyHint=false, destructiveHint=false). The description adds the base64 input format and record-targeting behavior, but does not disclose whether repeated uploads create duplicates, size limits, permission requirements, or side effects associated with openWorldHint=true. No contradiction 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 a single, efficient sentence that front-loads the action and key parameters. Every word contributes meaning, and there is no redundant or filler content.

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 core operation is clear, but there is no output schema and the description does not indicate what the tool returns upon success/failure, any prerequisites, or potential side effects. Given the seven-parameter schema and openWorldHint, slightly more context would help an agent confidently invoke the tool and interpret the result.

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 seven parameters, including the plan-mode 'apply' nuance and base64 encoding of content. The description reinforces table + sys_id as the record locator but adds little beyond the schema, matching the baseline for high schema coverage.

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 clear verb ('Attach'), a specific resource ('a file'), and the target ('a record identified by table + sys_id'), making the tool's action unambiguous. It is naturally distinguishable from sibling attachment tools like get_attachment, download_attachment, and delete_attachment.

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 clearly implies the use case: upload an attachment to an existing ServiceNow record using its table and sys_id. It does not explicitly discuss when not to use it or name alternative tools, but the phrasing gives enough context that an agent can route to this tool for uploads.

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 adds meaningful side-effect context beyond the annotations: it discloses persistence to the env file and clearing of identity-scoped caches (OAuth tokens, schema, plugin availability). This is useful behavioral disclosure even though destructiveHint=false; clearing caches is not presented as destructive to persistent data.

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. The primary action is front-loaded, and the side-effect detail is presented in a compact second sentence with no filler.

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

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

For a simple profile-switching tool, the description, paired with parameter schema and annotations, covers the essential behavior, persistence, and cache effects. It does not mention return values or error conditions, but the absence of an output schema and the tool's simple state-changing nature make this a minor gap.

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

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

Both schema parameters already have clear descriptions: 'name' indicates the profile to activate and 'instance' explains the per-call override with a pointer to servicenow_list_instances. Since schema coverage is high, the description does not need to add parameter detail, and it does not.

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 ('Switch') and resource ('active ServiceNow connection profile'), and specifies it is persisted to the env file. This clearly differentiates it from sibling tools like servicenow_list_instances or servicenow_set_credentials.

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

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

The description implies the tool is used when you want to change the active ServiceNow profile, but it does not explicitly compare with alternatives or state when not to use it. The schema references servicenow_list_instances for discovering profiles, but the description itself gives no usage guidance beyond the core action.

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