now-sdk-ext-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v4.5.0
Disambiguation4/5
Most tools have clearly distinct purposes, with detailed descriptions that differentiate overlapping areas like flow execution (test_flow vs execute_flow) and queries (query_table vs aggregate_query vs count_records). A few pairs, such as get_app_details and lookup_app, could cause initial confusion, but the descriptions resolve this. Overall, the boundaries are well-defined despite the large number of tools.
Naming Consistency4/5
The vast majority of tools follow a consistent verb_noun pattern (e.g., get_catalog_item, list_attachments, create_update_set), making predictions easy. Minor deviations like aggregate_grouped and code_search break the pattern slightly but are still readable. The naming is largely predictable and coherent.
Tool Count1/5
With 87 tools, the count is extreme and far exceeds the rubric's 50+ threshold. While the server covers a broad ServiceNow domain, the sheer number makes it unwieldy for agents to select from and likely includes redundant or overly granular operations. This is a case of quantity over an appropriately scoped tool surface.
Completeness4/5
The tool surface is exceptionally comprehensive, covering CRUD operations, queries, aggregates, flow automation, CMDB traversal, code search, app management, ATF testing, knowledge management, script push/pull, and update sets. Minor gaps exist, such as no dedicated single-record delete tool, but workarounds via query_delete_records or execute_script fill the void. Overall, the domain is well-covered with no significant dead ends.
Average 4.2/5 across 87 of 87 tools scored. Lowest: 3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 24 commits in the last 12 weeks
- Last stable release on August 5, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only (readOnlyHint=false) and has open world side effects (openWorldHint=true). The description adds only 'This creates a new update set on the instance,' which is redundant with the tool's name. It does not disclose potential side effects, permissions required, or implications of creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, but the 'IMPORTANT' sentence is somewhat redundant with the title and adds little value. It is not wasteful, but it could be more informative with the space used.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with no output schema and minimal annotations, the description should explain prerequisites, potential side effects, or what happens on success. It lacks any contextual information beyond the action itself, making it incomplete for an agent to understand the full impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with detailed descriptions (name, instance, application, description). The tool description adds no additional parameter semantics beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Create a new update set.' This is a specific verb+resource pair that distinguishes it from sibling tools like clone_update_set, list_update_sets, or set_current_update_set. The added 'IMPORTANT' clause reinforces that it operates on the instance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention scenarios where creating an update set is appropriate or when to prefer clone_update_set or set_current_update_set. The description provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, establishing the read-only safety profile. The description adds context about sys_app records and optional filtering, but does not disclose return format, pagination, or auth details beyond the schema's instance parameter. Minimal behavioral disclosure beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action ('List') and resource, with no redundant or extraneous content. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with a comprehensive schema, the description is mostly complete. The main gap is lack of sibling differentiation and return format details, but given the low complexity and presence of annotations, it is adequately contextual.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for limit, query, and instance. The description's mention of 'optional filtering' adds no new semantic value beyond what the schema already provides, 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.
Purpose5/5
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 'scoped applications (sys_app records)', clearly indicating the tool lists scoped app records on the instance. It distinguishes from siblings like list_company_apps by explicitly targeting 'scoped' applications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as list_company_apps or get_app_details. The description only states what it does, without context for selection or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, so the safe read nature is conveyed. The description adds the item count detail but does not disclose additional behavioral traits like authentication requirements or return format, which are not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the purpose and key detail without any filler. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only tool with fully described parameters and no output schema. The description gives enough context (including the item count) to select and invoke the tool, though it could explicitly mention expected return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters fully described. The description only mentions sys_id and does not add meaning beyond the schema. Baseline of 3 is appropriate since the schema carries the parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'gets details of a specific service catalog category by sys_id', which is a specific verb+resource+scope. It also mentions the item count, distinguishing it from sibling tools like list_catalog_categories and get_catalog_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need details of a specific category identified by sys_id, but it does not explicitly state when to use it over alternatives or provide exclusions. The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, and the description is consistent with these. The description adds no extra behavioral context such as return value format or potential errors, but for a simple read-only getter, the annotations sufficiently cover 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the purpose with no redundant words. It is optimally concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description covers the essential purpose. It does not explicitly describe the return value format, but the name and wording imply the current scope name. Given the low complexity and good annotations, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single 'instance' parameter with a detailed description, achieving 100% schema coverage. The tool description adds no additional parameter semantics, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Get') and resource ('currently active application scope'), making it distinct from related tools like set_current_scope or get_app_details. It is unambiguous and directly conveys the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: the tool is for when one needs to know the current application scope. However, the description does not explicitly mention when to prefer this over alternatives (e.g., set_current_scope) or any prerequisites, leaving the agent to infer the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read nature is known. The description adds the sc_category table context and filter options, but it does not disclose the return format, pagination defaults, or any side effects beyond what annotations imply. This is reasonable but not rich behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action ('List service catalog categories'), and every word earns its place. It avoids fluff and presents the most important usage guidance succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with good annotations and a fully documented schema, the description is nearly complete. It conveys the resource, table, filters, and use case. It does not explicitly mention pagination or limits, but those are in the schema, so the description is adequate for tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 8 parameters individually described. The description reinforces which parameters are useful for filtering (parent category, catalog, active, title) but does not add syntax or format details beyond the schema. Baseline 3 is appropriate when the schema carries the full parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists service catalog categories from the sc_category table and mentions key filters. It distinguishes the list operation from related single-item tools like get_catalog_category through the plural 'categories' and the phrase 'browse the catalog's organizational structure,' though it does not explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool ('Use this to browse the catalog's organizational structure') and lists likely filter criteria. However, it does not explicitly state when not to use it or mention alternatives such as get_catalog_category for retrieving a single category, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the annotations: it validates the app exists, records previous scope, verifies the change, and warns that it changes the session's application context. This provides insight into side effects and safety, which is valuable since the tool is a write operation (readOnlyHint=false). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: three sentences that state the primary action, key validation steps, and an important warning. Every sentence earns its place, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 params, no output schema) and the presence of annotations, the description covers the essential aspects: what it does, key behaviors (validation, recording, verification), and the session context side effect. It does not describe the return value or error handling, but 'verifies the change' implies feedback, and the annotations cover safety. This is complete enough for an agent to use correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, fully documenting the 'instance' and 'app_sys_id' parameters. The tool description does not add additional meaning beyond the schema, which is acceptable given the schema already provides comprehensive parameter semantics. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Change the active application scope.' It uses a specific verb and resource, and adds detail about validation, previous scope recording, and verification. However, it does not explicitly distinguish itself from sibling tools like get_current_scope or list_scoped_apps, though its unique purpose is evident from the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the action ('Change the active application scope') and warns about the session context change, but it does not provide explicit when-to-use guidance or mention alternatives. The context is clear enough to infer when this tool should be used, but there is no direct comparison to other scope-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=false, so the description's 'IMPORTANT: This creates a new category on the instance' adds minimal new information beyond emphasizing persistence. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with two short sentences plus an emphasis line. The IMPORTANT sentence is somewhat redundant, but it does not waste much space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with full schema coverage, the description covers purpose and key parameters. It does not mention return value or error behavior, but no output schema exists and tool complexity is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already well-documented. The description repeats that label and knowledge_base_sys_id are required and parent_category is for subcategories, adding no new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' with a clear resource 'category in a knowledge base'. It clearly distinguishes this from sibling tools like list_kb_categories or get_knowledge_base.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states required inputs (label, knowledge_base_sys_id) and optional parent_category, giving clear context for when to use. It doesn't explicitly name alternatives, but the create operation is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as mutating and non-idempotent. The description adds valuable behavioral context: comments are customer-visible by default, while work notes are internal to fulfiller staff. It does not contradict the annotations and goes beyond their basics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first states the core function and scope, the second clarifies the key parameter behavior. It is concise, front-loaded, and contains no superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with no output schema, the description covers the essential context: what the tool does, what record types it applies to, and how to switch visibility. It doesn't mention return values or error handling, but those are less critical for this kind of tool and the schema documentation fills in the parameter gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, so the baseline is 3. The description reinforces the is_work_note parameter's effect but adds no new details beyond what the schema already states (e.g., visibility semantics). No additional parameter-level insight is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Add') and resource ('a comment or work note to any task-based record'), and explicitly names example record types. It clearly distinguishes the tool's function from sibling tools like assign_task or close_incident by focusing solely on adding comments/notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool's purpose and the two modes (comment vs. work note), so an agent knows when to use it. However, it does not explicitly mention when not to use it or point to alternative tools for other record modifications, leaving the differentiation to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint, so the bar is lower. The description adds that it 'returns per-group statistics' and works on 'any' table, reinforcing but not substantially expanding beyond annotation-driven expectations. It omits details like default behavior if no aggregate functions are specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences plus a list of examples. It is front-loaded with the core behavior and every sentence earns its place with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters, no output schema), the description covers the core use case and examples. It lacks details on return format and edge cases (e.g., behavior when no aggregate function is selected), but annotations and rich schema descriptions fill many gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all 11 parameters having descriptions. The description adds illustrative examples but does not explain parameters beyond the schema. The baseline of 3 is appropriate since the schema takes the primary burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run aggregate functions'), the resource ('any ServiceNow table'), and the distinguishing grouping behavior ('grouped by a field'), which separates it from sibling tools like aggregate_query and count_records. The examples further illustrate its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'ideal for breakdowns and dashboards' and concrete examples ('count of incidents grouped by priority') give clear context for when to use this tool. However, it does not explicitly contrast with alternative tools like aggregate_query or define when grouping is unnecessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'IMPORTANT: This modifies records' is consistent but largely redundant. It does not add deeper behavioral context such as partial failure semantics or permissions, but there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, each serving a clear purpose: stating the operation, outlining the update structure, and reinforcing the mutating nature. No filler or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations and 100% schema coverage, the description is complete enough for a batch update tool. It clearly states the action and the data shape, though it could briefly note non-atomic behavior; the stop_on_error parameter in the schema partially covers that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description only restates the core per-item fields (table, sys_id, field data). It does not add meaning beyond what the input schema already provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb 'Update' and a clear resource: 'multiple records across one or more ServiceNow tables in a single batch.' This makes the tool's purpose immediately evident and distinguishes it from create or query-based update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates when to use this tool: when updating multiple records across one or more tables in a single batch. It does not explicitly name alternatives like query_update_records, but the context is unambiguous and sufficiently scoped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, non-idempotent, and non-destructive. The description adds useful context by explicitly noting the tool creates a new update set, copies all records, and starts in 'in progress' state. However, the phrase 'all records on the instance' is ambiguous (could be misread as instance-wide rather than from the source update set), and there is no mention of permissions or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, with the core action stated in the first sentence. The IMPORTANT note adds emphasis on the side effect but is not excessively verbose. Every sentence contributes to understanding the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with three fully described parameters and no output schema, the description covers the action, the resulting state, and the side effect. It lacks information about return values and potential failure conditions, but given the low complexity and existing annotations, it is reasonably complete. The ambiguity in 'all records on the instance' slightly detracts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 three parameters. The description only indirectly references new_name ('specified name') and source_sys_id ('existing update set') without adding meaningful details beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clones an existing update set by creating a new one and copying all its records, specifying the resulting state ('in progress'). The verb 'clone' and resource 'update set' are specific, and the behavior is distinct from sibling tools like create_update_set or move_update_set_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (duplicating an update set) but does not explicitly state when to use this vs alternatives like create_update_set or move_update_set_records. No exclusions or alternative comparisons are provided, leaving the agent to infer usage from the term 'clone'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful details about the output content (type, constraints, help text, choice values), but it does not disclose any additional behavioral traits such as failure modes, permission requirements, or whether fields without choices are omitted. With annotations present, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the exact purpose and output contents, the second gives a clear usage directive. It is front-loaded, no filler, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only explanation tool with no output schema, the description covers the main intent, output expectations, and a usage cue. It does not mention error scenarios (e.g., field not found) or distinguish from similar field-related tools, but it is largely complete for its simplicity. A 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — every parameter (table, field, instance) has a meaningful description. The tool description itself does not add parameter-specific details beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get detailed explanation') and resource ('a specific field on a ServiceNow table'), and enumerates what the explanation includes (type, constraints, help text, choice values). This makes it clearly distinct from sibling table-level tools like 'discover_table_schema' or 'lookup_columns'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'Use this to understand what a field does... before reading or writing data.' This tells the agent when to use it, though it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint: true, so the agent knows this is a safe read operation. The description adds the 'for the session' scoping detail, which is useful context beyond the annotations. However, it does not disclose what happens if no active update set exists, potential errors, or the exact return format, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence containing exactly the necessary information—no wasted words. It is concise and well-structured, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one optional parameter, no output schema, read-only annotation), the description is mostly complete. It clearly states what is retrieved. However, it omits any detail about the return object's shape or possible error conditions, which would be useful for full completeness, especially since no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100% for the single 'instance' parameter, so the schema already fully documents its purpose. The description adds no parameter-related information, which is acceptable given the schema's completeness. The baseline score of 3 applies because the structured data does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource ('currently active update set'), which distinguishes it from sibling tools like 'list_update_sets' (lists all) and 'set_current_update_set' (sets). The phrase 'for the session' adds scope, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool—when you need the active update set in the current session. However, it does not explicitly mention alternatives or exclusion criteria, such as 'use list_update_sets to see all sets' or 'use set_current_update_set to change it.' Despite this, the context is clear enough for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as mutative (readOnlyHint false) and destructive (destructiveHint true). The description reinforces this with 'mutative operation that creates or updates records' and adds a caution to verify content. It does not contradict annotations, but adds limited new behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the first sentence immediately stating the action and mechanism. The second sentence adds a clear warning and use cases. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema) and the presence of annotations, the description is largely complete. It covers purpose, usage, and safety, but could potentially mention error handling or what the response looks like. Overall, it is sufficient for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so the schema already fully describes each parameter. The description adds minimal new information about parameters, only referencing the XML format which is also mentioned in the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool imports XML records into a ServiceNow instance via the sys_upload.do processor, and specifies the format as ServiceNow unload XML. It distinguishes itself from sibling tools like export_record_xml by being the import counterpart, and from other creation tools by focusing on XML content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'for restoring configurations, migrating records between instances, or applying exported record definitions.' It also provides a clear caution about verifying XML content and target table. However, it does not explicitly mention alternatives or when not to use it, which is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true and openWorldHint=true, and the description does not contradict these. The description adds value by describing the returned metadata fields and optional filters, which is useful given the lack of an output schema. However, it does not disclose pagination or rate limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences that front-load the main purpose and return information. It is appropriately sized with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list operation, no output schema, and full schema parameter coverage, the description adequately covers the tool's purpose, return fields, and filters. It could benefit from noting behavior when no filters are applied, but overall it is complete enough for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all four parameters (scope, sys_id, instance, installed_only). The description only restates the filter options and does not add additional parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists company-internal applications and specifies the metadata returned (name, scope, version, install status, update availability). This distinguishes it from siblings like search_store_apps and get_app_details by focusing on internal shared applications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for listing company-internal applications but does not explicitly state when to use it versus alternatives like search_store_apps or list_scoped_apps. No exclusions or alternative recommendations are provided, so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the table source and filter options, but no additional behavioral context like pagination or return format. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, then a concise list of filters, then a purpose statement. No redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with 100% schema coverage and no output schema, the description covers the main purpose and filters. It does not explain return shape or pagination, but the schema handles parameter details, so this is adequate if not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 7 parameters. The description repeats filter names (knowledge base, parent category, active status, encoded query) but adds no new semantic meaning beyond grouping them together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'List knowledge base categories from the kb_category table.' It clearly differentiates from sibling tools like list_kb_articles (articles) and list_knowledge_bases (bases), and mentions key filters to scope the listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context: 'Use this to understand a KB's taxonomy before creating or categorizing articles.' This implies when to use it, though it does not explicitly mention alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which covers the safety profile. The description adds the notion of optional filtering but does not disclose pagination, ordering, or response format. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, and contains no unnecessary words. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description, schema, and annotations are sufficient. The schema covers all parameters, annotations cover safety, and the description states the operation. The lack of an output schema is acceptable since the return type (list of update sets) is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have descriptions in the schema, so coverage is 100%. The tool description only references 'optional filtering' which maps to the query parameter, but adds no extra details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('update sets'), and scope ('on the instance'), and mentions optional filtering. This distinguishes it from sibling tools like create_update_set, inspect_update_set, or get_current_update_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear use case: listing update sets with optional filtering. However, it does not explicitly mention when not to use it or name alternatives, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that script content is read from the appropriate table and written to the specified file path, adding mechanistic detail beyond the annotations. It does not mention file overwrite behavior or potential errors, but the annotations already signal destructive and non-read-only behavior, so the description adds reasonable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, beginning with a concise action statement and followed by a clean list of supported script types. Every sentence is informative, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that writes a script to a file, the description covers the core behavior and supported types. It does not describe return values or error cases, but these are less critical given the output is a file. The schema and annotations fill most gaps, making the description sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes every parameter. The description adds a mapping of script type names to table names, which are largely redundant with the enum values. It does not significantly enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: pulling a script from ServiceNow and saving it to a local file. It lists the specific script types supported, distinguishing it from the sibling push_script by direction (pull vs. push).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to obtain script content locally) but does not explicitly contrast it with alternatives like push_script or execute_script. No exclusionary or alternative-based guidance is given, leaving usage implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only, and the description adds a explicit warning that the tool creates an attachment, which reinforces the mutating nature. It does not disclose additional behavioral traits like return values or permission requirements, but the core side effect is covered. This is adequate but not rich beyond annotation provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with the purpose stated in the first sentence and the critical constraint and side effect highlighted in the following sentences. Each sentence adds value without redundancy or unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a straightforward purpose and no output schema, so the description covers the essential action and the critical base64 encoding requirement. It does not mention potential errors, size limits, or success responses, but these are not needed for basic usage. The instance fallback is documented in the schema, so there is no significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All six parameters are fully described in the input schema with detailed descriptions and examples. The description adds no new parameter information beyond restating the base64 encoding requirement, which is already present in the schema. With 100% schema coverage, the schema carries the full burden and the description adds minimal extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Upload' and clearly identifies the target resource as a ServiceNow record, making the operation unambiguous. It naturally distinguishes from sibling tools like get_attachment_info and list_attachments by framing this as a creation action. The base64 requirement is an additional clarifying detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for attaching files to records, which is distinct from reading or listing attachments. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full guidance. The context is clear and there are no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint and openWorldHint, so the safety profile is known. The description adds valuable transparency by detailing the validation checks performed and the return payload structure (valid/invalid flag, counts, issues with severity, component, sys_id, description, suggested fix). This exceeds what annotations reveal, though it stops short of describing edge-case behavior like missing sys_id handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose, followed by specific checks and return details. Two short paragraphs without redundancy or filler—every sentence contributes essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity, the description adequately explains what the tool does, what it validates, and what it returns. Since there is no output schema, the return structure is described in useful detail. Missing behavior on nonexistent items or permission requirements is not disclosed, but the description is sufficiently complete for a read-only validation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters fully with descriptions (instance auth alias, catalog_item_sys_id). The description does not add further parameter-level meaning beyond restating that it validates a catalog item, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates a catalog item's configuration on ServiceNow, enumerating specific checks (duplicate variables, missing names, inactive mandatory variables, UI policy issues). This specific verb-resource combination distinguishes it from siblings like validate_app_install or get_catalog_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by stating what the tool does and what it checks, but it does not explicitly specify when to use it over alternatives or provide exclusions. No mention of when not to use this tool or why pick it over validate_app_install for configuration validation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond annotations: operations are sequential, variable references are supported via saveAs/${key}, and there is an explicit warning that records are created on the instance. Annotations already indicate this is a write operation (readOnlyHint=false), so the description complements rather than repeats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the core function, then explaining variable references, followed by an illustrative example and a brief warning. It is somewhat verbose but each section earns its place by clarifying key usage patterns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with multi-step operations and variable references, the description covers the essential behavior, including sequential execution, saveAs mechanics, and a warning. It does not discuss transaction behavior or return values, but the schema covers the transaction parameter and there is no output schema, so the description is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description enriches parameter understanding by explaining how saveAs and ${name} references work together with a concrete example. This is beyond the schema's basic field descriptions, providing practical semantics for the operations array.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create multiple records across one or more ServiceNow tables in a single batch.' It uses a specific verb ('Create') and resource ('records across ServiceNow tables'), and the batch context distinguishes it from single-record creation and other batch tools like batch_update_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool's capability and provides an example of sequential dependency, but it does not explicitly state when to prefer this over alternatives like batch_update_records or query_update_records. The use case is implied but not directly contrasted with siblings, so it meets the minimum for clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it's a safe read operation. The description adds the return fields (file name, content type, size, attached record), which is useful but not extensive. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, information-dense sentences. The main action is front-loaded, and every word earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool, the description covers the essential elements: what it does, what identifier is needed, and what it returns. The instance param is self-explanatory in the schema, and the absence of an output schema is compensated by listing return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—both params have clear descriptions. The description's mention of 'sys_id' merely echoes the schema, adding no significant extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get metadata' plus resource 'attachment' and identifier 'sys_id', making the purpose immediately clear. It distinguishes itself from sibling tools like list_attachments and upload_attachment by focusing on a single attachment's metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the usage context: when you have a specific attachment's sys_id and need its metadata. It does not explicitly name alternative tools or exclusions, but the context is unambiguous, preventing confusion with listing or uploading tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context by explaining the underlying table hierarchy (sys_scope, sys_app, sys_store_app, sys_plugins) and listing the returned fields (sys_id, name, scope, version, active status, type). This goes beyond the annotations and provides useful behavioral expectations, though it omits details like potential result size limits or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized but well-structured: it opens with the core purpose and return fields, then provides a hierarchy breakdown, followed by key use cases. Every section adds value and the text is not redundant. It could be slightly tighter, but the length is justified given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four parameters and no output schema, the description compensates by listing the return fields and providing use-case context. It covers the main scenarios (retrieving sys_id, checking active status, looking up version/scope). However, it does not mention how results are ordered or paginated, and the absence of an output schema means some additional return-structure details could be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (type, instance, active_only, search_term) is already well-documented in the input schema. The description adds no additional parameter-specific meaning beyond what the schema already provides; it only clarifies the table structure indirectly related to the 'type' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Search for ServiceNow applications (scoped apps) and platform plugins by name, scope namespace, or plugin ID.' It specifies the resource (apps and plugins) and the action (search), and differentiates itself from siblings like get_app_details, list_plugins, and search_store_apps by emphasizing cross-table search across sys_scope and sys_plugins.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete use cases, such as finding an app's sys_id for execute_script and checking installation/active status. It establishes context for when to use the tool, but does not explicitly mention alternatives or exclusion conditions. The hierarchy explanation helps users understand what each type filter covers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds valuable transparency by stating that it uses the Stats API and returns computed statistics without individual records, which helps the agent anticipate the output. It does not discuss rate limits or authentication, but given annotations cover safety, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first defines the tool's function, the second provides illustrative examples. It is front-loaded, with no redundant phrases or filler content. Every sentence contributes to understanding the tool's purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 9 parameters and no output schema, the description does not explain the exact structure of returned statistics. However, the schema thoroughly documents all inputs, and the description clarifies what the tool returns (computed statistics, not records). The examples provide real-world context. Slight gap in not describing output format, but overall adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 with its own description. The tool description does not add significant parameter-level detail beyond naming the aggregate functions, which maps directly to the array fields (avg_fields, max_fields, etc.). Since the schema carries the semantic load, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs aggregate functions (COUNT, AVG, MIN, MAX, SUM) on ServiceNow tables using the Stats API. It explicitly notes that it returns statistics without individual records, which distinguishes it from query_table and count_records. The inclusion of concrete examples (average resolution time, max priority, etc.) further clarifies the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical use cases through examples, indicating when the tool is appropriate. However, it does not explicitly mention alternatives or situations where a different sibling tool (e.g., aggregate_grouped or count_records) would be preferred. The phrase 'on any ServiceNow table' implies general applicability, but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the specific mutation (sets approval field to 'approved') and emphasizes that it changes the approval status. This adds useful context beyond the annotations (readOnlyHint=false, idempotentHint=true) and does not contradict them. It could also mention idempotent behavior, but the annotation covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler. The action, object, and effect are front-loaded, and the 'IMPORTANT' warning adds emphasis without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write operation with full schema documentation and no output schema, the description covers purpose, effect, and safety warning. It does not explain behavior for already-approved requests or error conditions, but the idempotent annotation and general simplicity make this adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter (sys_id, comments, instance) is already well-documented. The description adds no new meaning beyond reiterating 'optional comments', which is already in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Approve'), identifies the resource ('change request'), and states the exact effect ('Sets the approval field to approved'). This clearly distinguishes it from sibling tools like close_incident or resolve_incident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to approve change requests, and the context makes it the only tool for that purpose among siblings. It does not explicitly mention alternatives or when not to use, but no conflicting tool exists, so the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and idempotentHint=true, but the description adds useful behavioral context by noting the assignment_group field is updated when provided. This clarifies the operational impact beyond the basic write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and target, followed by the scope. Every word earns its place, with no redundant information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward assignment operation with good annotations and full schema coverage, the description sufficiently covers purpose, scope, and a key behavioral detail. It does not explain return values, but no output schema exists and this is a simple write action, so completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already well-documented. The tool description adds limited new meaning—only the optionality of assignment_group—so it relies on the schema for parameter understanding, matching the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'assign' with a clear resource 'task record' and optional 'assignment group'. It also defines the scope as 'any task-based table', which distinguishes it from sibling tools that target specific task types or actions (e.g., close_incident, add_task_comment).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it works on any task-based table, clearly indicating broad applicability for assignment operations. However, it does not explicitly call out when not to use it or reference alternative tools, leaving some room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds irreversibility by stating 'the flow will be permanently cancelled and cannot be resumed'. This goes beyond the annotations and provides critical behavioral context. No contradiction exists between description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: two sentences plus a bolded important warning. It is front-loaded with the action, followed by usage guidance, then the critical destructive caveat. Every sentence serves a purpose with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with three parameters and no output schema, the description covers the what, when, and the irreversible consequence. It does not describe return values, but the tool is simple and annotations already convey the safety profile, so the overall context is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (reason, instance, context_id) are fully documented in the schema. The description reinforces the role of context_id but adds no additional parameter-level meaning beyond what the schema already provides, which fits the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair, 'Cancel a running or paused flow execution by its context ID', which clearly states what the tool does. This distinguishes it from sibling flow tools like execute_flow and get_flow_context_status by focusing on the cancellation action and the method (context ID).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly lists use cases ('no longer needed, is stuck in a waiting state, or was started by mistake'), giving an agent clear contexts for invoking the tool. It does not mention alternatives or when NOT to use it, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 valuable behavioral context: sections can be individually enabled/disabled, and it mentions the returned sections. This goes beyond the annotations and helps the agent understand the tool's flexibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and the second sentence adds a key capability (enable/disable sections) without redundancy. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and readOnly annotations, the description covers the tool's overall behavior, return content, and configurability. It does not detail output formatting or error cases, but for a health check tool with this level of annotation support, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented in the schema. The description gives a high-level overview but does not add parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Run' and clearly identifies the resource ('consolidated health check on a ServiceNow instance') and the outputs (version info, cluster node status, stuck scheduled jobs, active semaphore count, operational counts). This distinguishes it from sibling tools like query_table or aggregate_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit use case: 'Use this to quickly assess the overall health and status of an instance.' It does not name alternatives or exclusions, but the context is clear enough that an agent would know when to choose this tool over more specific query tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations by explicitly stating 'This changes the incident state' and specifying the exact state value. It also notes the prerequisite about Resolved state. The annotations (readOnlyHint=false, idempotentHint=true) are consistent with this, and the description adds useful context about state transitions without contradicting any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary action, and includes an IMPORTANT warning that draws attention to the key side effect. Every sentence serves a purpose with no redundant or extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-change operation with four parameters and no output schema, the description covers the core behavior, the state change, and a usage prerequisite. It does not explain return values or error behaviors, but these are not critical for this tool type, and the annotations provide additional context (idempotency, non-destructiveness). Overall, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already fully described in the schema. The description does not add parameter-specific details, but the baseline for high schema coverage is 3, and the description's mention of state (Closed) implicitly relates to the impact of parameters like close_code and close_notes without elaborating on them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Close an incident by setting state to Closed (7).' This is a specific verb and resource, and it explicitly distinguishes itself from sibling tools like resolve_incident by naming the target state (Closed vs. Resolved). The warning about the incident typically being in Resolved state also differentiates it from other state-changing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual guidance: 'The incident should typically be in Resolved state before closing, though this depends on instance configuration.' This implies the appropriate time to use the tool and a prerequisite. However, it does not explicitly name alternative tools or state when not to use it, so it doesn't fully meet the 'explicit when/when-not/alternatives' criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds context about using the Stats API and server-side efficiency. It does not mention potential errors or rate limits, but the added performance context goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: what it does, how it works, and when to use it. Information is front-loaded and there is no redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple count tool with no output schema, the description sufficiently covers purpose, use cases, and performance. It does not explicitly describe the return value, but the name and purpose make it obvious. The example queries in the schema provide enough operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents the three parameters (query, table, instance). The description only reiterates 'encoded query' and 'any ServiceNow table' without adding new semantic details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Count') with a clear resource ('records on any ServiceNow table') and explicitly mentions an optional filter ('encoded query'). It also distinguishes itself from retrieval tools by emphasizing efficient server-side counting via the Stats API.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit use cases ('gauge data volumes') and contrasts with the alternative of querying all records client-side. However, it does not mention when to use sibling aggregation tools (e.g., aggregate_query) instead, so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations declaring readOnlyHint=true and openWorldHint=true, the description adds value by detailing what will be returned (table name, label, parent class, per-field attributes) and explaining that optional flags query additional data sources like sys_choice. It does not contradict the annotations and provides useful context about the read-only, exploratory nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise. It opens with a clear summary sentence, follows with a compact return-value list, and then uses bullet points for key use cases. Every sentence provides useful information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has six parameters and no output schema, but the description compensates by explaining the return structure and the effects of optional flags. It covers the main use cases and clearly indicates the optional data that can be included. However, it does not exhaustively describe all edge cases or behavior for invalid tables, which keeps it slightly below a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides comprehensive descriptions for all six parameters, including examples and defaults (e.g., 'include_choices: Include choice values for fields that have them'). The tool description restates some of this information (e.g., 'optionally choice values') but does not add significant new semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Discover the full schema of a ServiceNow table including all fields, types, references, and optionally choice values, relationships, UI policies, and business rules.' This is a specific verb-resource combination that distinguishes it from sibling tools like lookup_table or explain_field by focusing on comprehensive schema discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Understand the structure of a table before querying or scripting against it', 'Discover reference fields', 'Find choice values', and 'Review UI policies and business rules'. This gives clear context for when to use the tool, though it does not explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds useful behavioral context: foreground blocks, background returns immediately with a context ID, and quick skips execution details. It does not restate annotations and provides mode-specific behavior beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear one-sentence purpose followed by a focused paragraph on mode behavior. Every sentence adds value and no content is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main execution modes, how to retrieve background results (naming follow-up tools), and when to use quick mode. It does not explain error handling or return formats, but the lack of an output schema shifts some burden to the description. Overall, it is sufficiently complete for a tool with 7 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all 7 parameters (100% coverage). The tool description does not add significant per-parameter detail, but it does contextualize the mode parameter within the foreground/background discussion. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Execute') plus a specific resource type ('ServiceNow Flow Designer action by scoped name'). The phrase 'Actions are the lowest-level building blocks' clearly distinguishes it from sibling tools like execute_flow and execute_subflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use foreground vs background modes and suggests background for flows with approval/wait steps. However, it does not explicitly name alternative tools for running full flows or subflows, so guidance on tool selection is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnly=false. The description adds valuable behavioral detail: foreground blocks until completion and returns outputs, background returns a context ID for polling, and quick mode skips execution detail records. It also clarifies that timeout only applies to foreground. This goes beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the core purpose and then expanding into mode behavior and input passing. Every sentence provides necessary context with no fluff. It's efficiently structured and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters with no output schema, but the description explains the key behavioral concepts: foreground vs. background, timeout scoping, and quick mode. It also points to follow-up tools for polling and retrieval. Minor gaps exist (e.g., error handling), but there are dedicated sibling tools for that, and the description is sufficiently complete for a complex execution tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have descriptions. The description adds a general note on passing inputs as key-value pairs, but this is already reflected in the inputs parameter schema. While the description doesn't rehash every parameter, it doesn't need to; the schema does the heavy lifting, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a ServiceNow Flow Designer subflow by scoped name' — a specific verb and resource. It differentiates from siblings by explicitly calling out subflows as 'reusable building blocks' and positions itself as 'the primary tool for testing subflows during development,' distinguishing it from execute_flow and execute_action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: foreground vs. background modes, with background explicitly recommended 'for flows with approval/wait steps.' It also references get_flow_context_status for polling, but it doesn't explicitly name alternatives like execute_flow or execute_action or state when not to use this tool. This is strong guidance but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool is known to be a safe read operation. The description adds valuable behavior context by naming the unload XML format and the endpoint, and noting the XML can be imported into another instance. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and front-loaded with the core purpose, followed by a bulleted list of use cases. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only export tool with three fully documented parameters and no output schema, the description covers the key context: purpose, format, endpoint, and likely use cases. The XML output is implied by the phrase 'generate ServiceNow-native XML,' which is sufficient for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (table, sys_id, instance) fully described. The description does not add additional parameter-level detail beyond the schema, but it reinforces the single-record scope and the XML format, matching the baseline for well-documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb and resource: 'Export a single record from a ServiceNow instance in unload XML format.' It specifies the endpoint and distinguishes itself from the sibling import_records_xml by emphasizing the export direction and single-record scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides four concrete common use cases (backup, transfer, comparing, update sets) that establish clear context for when to use the tool. It does not explicitly mention alternatives or when-not-to-use, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds valuable context by stating the output (list of tests with sys_ids) and how it connects to run_atf_test. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: first sentence states the core action, second explains the return value, third gives usage guidance. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by stating the return type and purpose. It covers the tool's role in the ATF workflow sufficiently for a search tool, though it could elaborate on output structure if needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all five parameters. The description's mention of 'name, description, or category' only echoes the schema's search_term and category definitions, adding no new parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for ATF tests with specific fields (name, description, category) and returns sys_ids for later execution. It distinguishes itself from the sibling run_atf_test tool by explicitly noting the chaining workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when you need to discover which ATF tests exist before running them,' providing clear usage context. It does not explicitly list exclusions or alternative tools, but the reference to passing sys_ids to run_atf_test implies the distinction from execution tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and openWorldHint, which already signal a safe, read-only operation. The description adds meaningful behavioral context by stating that it 'returns the full record if found, or a clear message if not,' which goes beyond the hints. It does not conflict with annotations and enriches the agent's expectation of outcome.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the purpose and examples, then immediately followed by usage guidance. Every phrase earns its place, with no redundant content. It is compact and easily parsed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with no output schema, the description covers purpose, return behavior, examples, and usage context. It does not detail the exact record structure, but 'full record' is sufficient for most cases. The instance parameter is explained only in the schema, but that is acceptable given schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with detailed descriptions for all three parameters (table, number, instance), so the description does not need to add much. It reinforces examples like 'INC0010001' that appear in the schema but adds no new meaning. Baseline 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (find), resource (task record), and scope (by number), with concrete examples (INC0010001, CHG0030002). It distinguishes itself from generic lookup siblings like query_table and lookup_table by focusing on task records with a number, which aligns with task-related siblings like assign_task and resolve_incident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool 'to look up sys_ids, check current state, or retrieve task details before performing actions like assigning or resolving.' This provides clear context for when to use it. However, it does not explicitly mention when not to use it or name alternatives (e.g., query_table for broader searches), so there are no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds what the tool returns (version, install status, etc.) but does not disclose any behavioral nuances like error handling, auth requirements beyond the environment variable, or potential side effects. This adds some context but not deep behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main purpose, and includes a helpful usage tip without unnecessary filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only detail-fetching tool with good annotations and clear usage, the description is mostly complete. It lists the key return fields and provides the lookup_app flow. However, there is no output schema, so the description could benefit from a bit more detail on the shape or structure of the returned metadata, but it is not essential for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (app_id, instance) have descriptive text in the schema. The description does not add meaning beyond the schema; it only restates that the tool works by sys_id, which is already in the schema. Thus baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get detailed information about a ServiceNow application by its sys_id' with a specific verb and resource. It also distinguishes itself from sibling tools like lookup_app by focusing on retrieving full details rather than resolving names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use lookup_app to find an application's sys_id by name, then use this tool to get full details.' This tells when to use this tool and names the prerequisite alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which covers the safety profile. The description adds valuable behavioral context about the optional 'include_variables' parameter and its default behavior, explaining that it retrieves form fields. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded. The first sentence states the core purpose, and the second provides a useful usage hint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with no output schema, the description is adequate. It covers the main purpose, optional variables, and usage context. It doesn't discuss error cases or return formats, but those aren't critical for this tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already well-documented. The description reinforces the 'include_variables' default but adds no new meaning beyond what's in the schema. Baseline 3 is appropriate since the schema carries the semantic burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get details of a specific service catalog item by sys_id, optionally including its variables.' This specific verb+resource combination distinguishes it from sibling tools like 'list_catalog_items' and 'list_catalog_item_variables'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: 'Use this to understand what a catalog item offers and what information is needed before submitting a request.' While it doesn't explicitly exclude alternatives, this guidance is sufficient for an agent to decide when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, so the bar is lower. The description adds valuable context: it specifies the underlying ProcessFlow API endpoint, states that flow operations logging is required, and explains that an unavailable report will include a notice. This goes beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise purpose statement, followed by usage guidance, endpoint context, an important prerequisite, and a typical workflow. Every sentence adds value and 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description compensates by listing the types of information returned (per-action timing, inputs, outputs, metadata) and provides context about the endpoint and prerequisites. It does not detail error handling or the exact response structure beyond the notice, but it is complete enough for a diagnostic tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all four parameters. The tool description does not add extra parameter-specific semantics beyond what the schema already provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and specifies the resource 'rich execution details for a flow context' including per-action timing, inputs, outputs, and high-level metadata. It clearly distinguishes itself from sibling tools like get_flow_context_status and get_flow_logs by emphasizing detailed per-action diagnostics and positioning itself as the primary diagnostic tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: after test_flow or execute_flow, for diagnosing failures, inspecting inputs/outputs, and iterating on flow definitions. It also includes a typical workflow and a prerequisite (flow operations logging must be enabled). It does not explicitly mention when not to use it or name alternative tools, so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description aligns with this by describing a read operation. It adds useful context by noting that the response includes the HTML body text, which goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two succinct sentences with action-first wording. Every sentence adds value, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has no output schema, and the description communicates that full content including HTML body is returned. This is sufficient for the agent to understand the result, though the exact response structure is not specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions for both sys_id and instance. The description mentions 'by sys_id' but does not add significant meaning beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get the full content of a knowledge article by sys_id, including the HTML body text.' This uses a specific verb and resource, and the focus on retrieving a single article by sys_id distinguishes it from siblings like list_kb_articles or create_kb_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use this when you need to read, review, or extract content from an article.' This gives clear context, though it does not explicitly mention alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds behavioral context by specifying exactly what details are returned (article and category counts) and positioning it as a scoping tool before browsing. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core function and include a usage guideline. No redundant information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with read-only annotations, the description adequately explains purpose, return content, and usage context. The lack of an output schema is compensated by mentioning the included counts. It does not specify error behavior, but that is not critical for this tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both sys_id and instance well-documented. The description's mention of 'by sys_id' adds no additional semantic meaning beyond what the schema already provides. Baseline 3 is appropriate because the schema carries the parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets details of a specific knowledge base by sys_id, including article and category counts. This distinguishes it from siblings like list_knowledge_bases (which lists all KBs) and get_kb_article (which gets article details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'Use this to understand the scope of a KB before browsing its contents.' It implies when to use this tool (as a precursor to browsing articles/categories) but does not explicitly mention alternatives or exclusions. However, the context is sufficient for a straightforward retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations readOnlyHint=true already convey a safe read operation. The description adds behavioral detail about output structure ('grouped by type'), which goes beyond the annotation. No contradictions or hidden side effects are mentioned; this is sufficient given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tight sentence with no unnecessary words. It front-loads the action verb, specifies the resource, and adds illustrative examples in parentheses—all without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, output format, and typical contents. While there is no output schema, the grouped-by-type description provides a mental model. It could mention limitations or dependencies, but for a read-only inspection tool, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for parameters sys_id and instance, so the baseline is 3. The description does not add parameter-specific semantics, but it implies the need for an update set identifier ('an update set's contents'). The schema already documents both parameters clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'inspect' and the resource 'update set's contents', and differentiates from sibling tools like list_update_sets by focusing on the components within an update set. The examples 'business rules, script includes' add specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies clear usage: when you need to see the components of a specific update set. It does not explicitly name alternatives or exclusions, but the context of 'inspect contents' is distinct enough to guide tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds valuable behavioral context by stating it returns metadata for each attachment including file name, content type, and size. It does not contradict annotations. While it lacks details about limit behavior or empty results, the annotation coverage makes this a strong 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core action and followed by a usage context sentence. There is no redundant or unnecessary phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with 100% schema coverage and good annotations, the description plus schema provide sufficient information for invocation. It clarifies the purpose and return type. A slight gap is not mentioning behavior for records with no attachments or whether pagination is expected, but overall it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all four parameters (limit, table, instance, record_sys_id) having clear descriptions. The tool description adds no additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'file attachments on a ServiceNow record', and specifies the return type (metadata with file name, content type, size). This clearly distinguishes it from sibling tools like get_attachment_info or upload_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use this to discover what files are attached to incidents, changes, catalog items, or any other record.' However, it does not mention when not to use it or point to alternatives, so it misses the 'when-not' element for a top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and open-world behavior. The description adds the source table and filter capabilities, which is useful context beyond the annotations. It doesn't describe return format, but with annotations the bar is lower.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main verb and resource. The first sentence covers functionality, the second covers usage context. Every word earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters but no output schema. The description adequately covers purpose and usage context, leaving parameter details to the schema. It could mention pagination or advanced query filtering, but given the schema and annotations, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented in the schema. The description paraphrases filter capabilities (text_search, category, catalog, active) but doesn't add new meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists service catalog items from the sc_cat_item table, and describes supported search and filtering. This distinguishes it from siblings like get_catalog_item and list_catalog_categories, which have different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to use for browsing/searching before getting item details or submitting a request. This implies exclusions (not for details/requests) but does not name alternative tools explicitly. Strong context but could be more direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the return fields (ID, name, version, active status) and the name-prefix search behavior, which goes beyond the annotation-provided information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and return value, followed by a concise usage guideline. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list tool with good annotations and complete schema coverage, the description is largely sufficient. It explains the return content and primary use cases, though it could optionally mention pagination or the default active-only behavior, but the schema already documents those details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description reiterates the name_prefix concept and active status but does not add significant meaning beyond the schema. It does not compensate for any missing schema detail, but none is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List ServiceNow platform plugins on an instance') and clearly states what is returned (plugin ID, name, version, active status). It addresses the intended use case of discovering installed/active plugins or finding one by name prefix, which distinguishes it from sibling tools that list other entity types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by stating when to use the tool: to discover installed/active plugins or find a plugin by name prefix. It does not explicitly mention when not to use it or alternatives, but the context is sufficient for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already indicating read-only and open-world behavior, the description adds valuable context by mentioning support for encoded query strings, field selection, and display value resolution. It does not contradict the annotations and gives a sense of the tool's capabilities beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear opening sentence stating purpose, followed by a brief capability summary and a usage note. Every sentence earns its place with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (6 parameters, no output schema), the description covers the main purpose, general applicability, and key features. It does not describe the return format or pagination details, but the schema and openWorldHint annotation reduce the burden on the description to cover those aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with detailed descriptions for all parameters, so the baseline is 3. The description mentions key features (encoded queries, field selection, display values) but does not add new parameter-level semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries any ServiceNow table via the Table API, using a specific verb and resource. It also distinguishes itself as general-purpose data retrieval, which separates it from sibling tools that target specific tables or operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by stating 'Use this for general-purpose data retrieval from any table,' which tells the agent when to choose this tool. However, it does not explicitly mention when not to use it or compare it with alternative sibling tools like lookup_table or query_syslog.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not destructive, and the description adds the critical behavioral detail that state changes to Resolved. The precondition about active states is useful context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly crafted sentences that front-load the purpose, followed by an important behavioral note. No redundant or filler content; every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: what it does, the key state change, and a crucial precondition. Given the tool's simplicity and the absence of an output schema, it is sufficiently complete for an AI agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters are documented in the schema. The description adds minimal extra meaning—it mentions resolution notes but does not enhance understanding of sys_id, instance, or close_code beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Resolve') with a clear resource ('incident') and includes the exact state change ('setting state to Resolved (6) with resolution notes'). This distinguishes it from siblings like close_incident and provides precise scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context by stating the incident must be in an active state (New, In Progress, On Hold) for success. However, it does not explicitly mention alternatives or exclusions, such as when to use close_incident instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations by noting that the tool will 'wait for all tests to complete,' indicating a blocking operation. It also specifies that it 'Returns a summary with pass/fail/skip/error counts,' which is not part of the annotations. Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate those, but it adds useful execution details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long with no fluff. The first sentence front-loads the core purpose and behavior, and the second sentence gives usage guidance. Every clause adds value, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters and no output schema, but the description adequately covers the high-level behavior and return value. It states the tool waits for completion and returns a summary with counts and status, which is sufficient for an agent to understand the outcome. It does not explain potential side effects or error conditions, but the annotations and schema provide enough detail for a moderately complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description repeats the 'provide exactly one' constraint for suite_name vs suite_sys_id, which is already stated in the schema property descriptions. It does not add new parameter semantics beyond what the schema provides, so no higher score is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Execute a ServiceNow ATF test suite and wait for all tests to complete.' It uses a specific verb ('Execute') and a specific resource ('Suite'), and differentiates from the sibling 'run_atf_test' by emphasizing the suite context. The mention of returning a summary with pass/fail/skip/error counts further clarifies the tool's output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes an explicit usage statement: 'Use this tool when the user wants to run a collection of ATF tests as a suite.' This provides clear context for when to choose this tool. It does not explicitly name alternative tools or state when not to use it, but the phrase 'as a suite' implies distinction from running a single test, which is present in the sibling tool list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds behavioral value by explaining the three tab_context modes and that the tool lists/browses rather than mutates. It does not detail result structure or API specifics, but the added tab contexts go beyond the annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose statement, a three-item bullet list for tab contexts, and a one-sentence usage line. It is front-loaded with the key action and contains no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the fully documented schema, read-only annotations, and a description covering purpose, tab contexts, and use cases provide sufficient guidance. It does not explain return formats or differentiate from sibling tools like get_app_details, but the absence of an output schema and the straightforward nature of the browse operation keep the gap small.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all parameters, including the enum values for tab_context. The description repeats the tab_context semantics (e.g., 'installed' → list all installed store applications) but adds little beyond 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search or browse ServiceNow store applications by category,' clearly specifying the action (search/browse), resource (store applications), and scope (category). It then enumerates three tab contexts, distinguishing this tool from siblings like get_app_details (fetches a single app) and install_store_app (installs an app).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Use this to discover what is installed, find available updates, or browse for new applications to install.' This gives clear context on when to invoke the tool, but it does not name alternative tools or exclusions (e.g., 'use get_app_details for a specific app'), so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and openWorld, so the bar for additional disclosure is lower. The description adds meaningful behavioral details: the BFS algorithm, returns nodes and edges up to a specified depth, and enforces limits (max depth 5, max nodes 1000). This provides context beyond the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient and front-loaded: the first sentence states the core function and algorithm, the second sentence gives use cases and key limits. Every sentence contributes value, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (6 params, no output schema) and strong schema coverage, the description provides sufficient context: it describes the traversal approach, return content (nodes and edges), and constraints. It does not detail the exact response structure, but since no output schema exists, this is a minor omission rather than a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter, including defaults and limits. The description repeats some limits (e.g., max depth 5, max nodes 1000) but does not add additional semantic value beyond what the schema already provides. It neither harms nor significantly enhances parameter understanding, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool traverses the CMDB relationship graph using breadth-first search, specifying the resource (CMDB graph) and the action (traverse). It also distinguishes this from sibling get_cmdb_relationships by emphasizing depth-based traversal, making its unique function clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names use cases (deep impact analysis, service mapping, understanding dependency chains), which provides clear context for when to use this tool. However, it does not mention alternatives or exclusion criteria, such as when to prefer the simpler get_cmdb_relationships for direct relationships.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructive (destructiveHint: true) and non-read-only (readOnlyHint: false). The description adds valuable context beyond annotations: partial update semantics ('Only the fields provided will be modified; all others remain unchanged') and a warning that it modifies the instance. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose. The second sentence is a clearly labeled IMPORTANT warning. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high schema coverage, clear annotations, and absence of output schema, the description is sufficient for a mutation tool. It explains the key behavioral nuance (partial update) and the mutating nature. It could mention what happens on success/failure, but the schema and annotations cover the main context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all parameters. The description adds important semantic context that omitted parameters remain unchanged, which gives meaning to the optional parameters as a group. This goes beyond what the schema states individually.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing knowledge article's fields with a specific verb ('Update') and resource ('existing knowledge article'). It also distinguishes from siblings like create_kb_article (creation) and get_kb_article (reading).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating existing articles by saying 'existing knowledge article's fields', but it does not explicitly state when to use this tool over alternatives (e.g., create for new articles, publish for workflow changes). The partial-update behavior is clear, but there is no direct 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the baseline for transparency is lower. The description adds value by disclosing the reporting behavior: it categorizes apps as valid, needing installation, needing upgrade, or having version mismatches. There is no contradiction with annotations, and nothing suggests side effects. It could elaborate on error handling or auth requirements, but for a read-only validation tool with good annotations, this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core action in the first sentence, and every clause adds relevant information. There is no fluff, repetition, or extraneous detail. It efficiently conveys what the tool does, what it reports, and when to use it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description does a good job of conveying the result categories: valid, need installation, need upgrade, version mismatch. For a validation tool with only two parameters (one required) and full schema documentation, this is sufficient context for an agent to select and invoke it. It does not describe the exact response format, but that is not necessary given the descriptive reporting behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of both parameters ('instance' and 'packages') with descriptive details, so the description does not need to repeat them. The description's mention of 'expected versions' loosely mirrors the 'requested_version' field but adds no new semantic information beyond what the schema already states. This meets the baseline for fully documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb 'Validate' and a clear resource: 'whether a set of applications are installed at the expected versions.' It sharply distinguishes from sibling install tools (e.g., install_from_app_repo) and lookup tools (e.g., get_app_details) by framing it as a read-only verification step. The added detail about reporting validity, installation needs, upgrades, and mismatches makes the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Useful for verifying environment readiness or checking deployment prerequisites' gives concrete context on when to use the tool. It does not explicitly mention when not to use it or name alternative tools, but the purpose is clear enough that an agent could infer that installation/comparison tools would be used for actual changes. This is clear contextual guidance without formal exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool 'modifies the code search configuration on the instance' and includes a warning to verify table name and fields. This adds context beyond the annotations, which already indicate readOnlyHint=false and destructiveHint=false. The behavioral effect on future searches is also explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with three sentences: purpose, prerequisites, and warning. It is front-loaded and every sentence contributes operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple 4-parameter tool with annotations and full schema coverage, the description covers the action, the prerequisite sys_id lookup, the effect on searches, and a safety warning. No output schema is needed, and the description adequately prepares the agent for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with detailed descriptions, including examples and references to lookup_table/lookup_columns. The tool description adds minimal param-specific detail beyond the schema, summarizing requirements but not enriching the semantics further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a new table to an existing code search group') and its effect ('expanding what gets searched'). It distinguishes from sibling tools like list_code_search_groups and code_search by focusing on the modification action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit prerequisites: 'Requires the search group's sys_id (get it from list_code_search_groups) and the table name and fields to search.' This tells the agent when to use it and what preparatory steps are needed. However, it doesn't explicitly contrast with alternatives for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining server-side execution with full GlideSystem API access, output via gs.print()/gs.info(), scope resolution nuances, and an explicit safety warning about executing code directly on the instance. These details add valuable behavioral context that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured in three focused paragraphs: an initial overview, a detailed scope behavior explanation, and a safety reminder. Each sentence serves a clear purpose, and the most critical information is front-loaded. There is no redundant text, making it highly efficient for its complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers the target endpoint, available APIs, output capture methods, scope behavior, and safety precautions. The schema and annotations further fill in parameter and safety details, leaving no major contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with rich descriptions for all four parameters (script, scope, params, instance), including syntax, defaults, and usage examples. The description itself adds little to parameter semantics; the schema already handles this dimension thoroughly, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Execute' and the resource 'JavaScript on a ServiceNow instance using Scripts - Background (the /sys.scripts.do endpoint)'. This distinguishes it from sibling tools like execute_subflow or execute_action, which target predefined workflows rather than arbitrary code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers implicit usage context by detailing scope behavior and warning to 'prefer read-only operations unless modification is explicitly intended,' but it does not explicitly state when to choose this tool over alternatives like execute_subflow or execute_flow. No direct comparisons or exclusions are provided, so guidance remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true annotation, the description correctly aligns as a read operation. It adds valuable behavioral context by explaining the precondition (only for failed flows) and that the return is the error message for diagnosing flow definition issues. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and immediately useful usage condition. Every sentence adds value, no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with 2 parameters and no output schema, the description fully covers purpose, usage trigger, parameter reference, and return value. It integrates well with sibling tools by referencing get_flow_context_status, and no critical information 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both instance and context_id fully documented in the schema. The description itself adds no additional parameter meaning beyond mentioning 'context ID' which mirrors the schema's required context_id field. Baseline 3 applies as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the error message from a failed flow execution by context ID, using specific verb 'retrieve' and naming the exact resource. It distinguishes itself from sibling tools like get_flow_logs and get_flow_outputs by focusing specifically on the error message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-to-use: 'Call this after get_flow_context_status shows ERROR'. However, it does not explicitly mention when not to use it or name alternative tools for related diagnostic needs, so it falls short of full alternative/exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, the description adds value by clarifying the return format (output name-value pairs) and the prerequisite status condition. It doesn't disclose failure behavior, but also doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences that front-load the core action and add a key precondition. No redundant phrases or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only retrieval tool with full schema coverage, the description covers what it returns, the precondition, and the resource type. It is sufficient for an agent to know when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both parameters (context_id and instance), achieving 100% coverage. The description repeats 'context ID' but adds no additional parameter-level detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve outputs from a completed flow/subflow/action execution by its context ID,' specifying the verb, resource, and key parameter. It distinguishes from sibling tools like get_flow_context_status (status) and get_flow_logs (logs) by focusing on the output values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly conditions usage on get_flow_context_status showing COMPLETE, providing a clear when-to-use rule. It doesn't name alternatives or exclusions, but the precondition is specific and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint, so the description gains credit for adding the default inclusion of variable sets and the specific return fields. It also notes the ability to disable variable sets via a parameter. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two short paragraphs. The first states the action and output, the second provides essential usage context and example variable types. Every sentence earns its place, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with no output schema, the description is complete: it details the return fields, explains when to use it (before submit_catalog_request), and describes the default behavior regarding variable sets. No critical information is missing for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema; it mentions variable set inclusion in prose but this is already covered in the include_variable_sets parameter description. The description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists variables (form fields) for a specific catalog item, enumerating the return fields (names, types, mandatory, defaults, help text). This distinguishes it from sibling tools like list_catalog_items or get_catalog_item which operate on catalog items themselves, not their variables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states this tool is 'Essential for understanding what data to provide when using submit_catalog_request', giving a clear when-to-use scenario. It does not mention when not to use it or name direct alternatives, but the context is strong enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds transparency by explaining what the returned tables represent: 'These are the tables and fields that are searched when performing a code search with that group.' This goes beyond the annotation by clarifying the output semantics. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-structured: two paragraphs, each sentence adding value. The first sentence states the primary function, the second clarifies what the results mean, and the third/fourth provide usage guidance. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool, the description is complete. It explains the output (tables and fields), provides use cases, and references sibling tools for related actions (`add_code_search_table` and `list_code_search_groups`). With annotations covering safety and schema fully documenting parameters, no additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, including the note that `search_group` is the NAME (not sys_id) and to use `list_code_search_groups` for available groups. The description itself does not add additional parameter details beyond the schema, so the baseline score of 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List the tables associated with a code search group.' It uses a specific verb ('List') and resource ('tables') and distinguishes itself from siblings by explaining these are the tables and fields searched during a code search. It also references related actions like `add_code_search_table`, further clarifying its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Use this to understand what a search group covers, or to identify if a specific table is missing and needs to be added via add_code_search_table.' This tells the agent when to use the tool and introduces an alternative (`add_code_search_table`) for the case when a table is missing. It could more explicitly name non-use situations, but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, so the read-only nature is given. The description adds useful behavioral context by specifying the source table and the optional filtering by active status and encoded query, going beyond what annotations provide without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences: the first states the core functionality and source, the second provides a clear usage context. Every word is purposeful, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description, combined with rich parameter schemas and annotations, fully covers the essential context for a read-only list operation. It explains the data source, optional filters, and a typical use case, making it complete for an agent to select and use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter thoroughly described. The description adds minimal value beyond the schema, merely summarizing that filtering by active and query is possible. This aligns with the baseline of 3 for a schema-rich tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists knowledge bases on a ServiceNow instance, with a specific resource (kb_knowledge_base table) and distinguishes it from sibling tools like list_kb_articles and get_knowledge_base by focusing on the discovery of KBs rather than their contents or individual retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case ('Use this to discover available KBs before browsing articles or categories'), implying when it should be used relative to other tools. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by stating it queries sys_dictionary and enumerates the return fields (element name, label, type, etc.), giving the agent a clear model of the tool's behavior beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear opening sentence, a purpose-driven bullet list, and a return-value summary. No redundant or filler content, and 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description clearly states what the tool returns (fields list). It also covers typical use cases and points to sys_dictionary, making the tool understandable in context. With thorough parameter descriptions in the schema, the overall description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description's bullets imply parameter usage (e.g., search_term for finding elements) but don't add meaning beyond what the schema already describes for each parameter. Thus no bonus beyond baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('List or search columns (fields) on a ServiceNow table') and clarifies the underlying mechanism (queries sys_dictionary). It also lists concrete use cases (validate column, find internal element name) that distinguish it from generic query tools like query_table or lookup_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use this tool to' section provides clear context for when to invoke this tool (e.g., listing columns, validating names, checking types). However, it does not explicitly mention alternative tools or when not to use it, so it falls short of the full 5 criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. The description adds that it queries sys_db_object, returns specific fields (name, label, parent, extendable, number prefix, scope), and that search is case-insensitive partial matching. This enriches the tool's behavior beyond the annotations, though it doesn't discuss pagination limits (covered by schema) or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, a bulleted use-case list, and a returns line. It avoids redundancy and uses short, scannable phrases. Every section adds value, making it both concise and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only metadata lookup tool, the description covers purpose, use cases, and return fields. The schema documents all parameters, and annotations declare safety. No output schema exists, so explaining the return fields is valuable and done well. The description is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides comprehensive descriptions for all three parameters, achieving 100% coverage. The description's mention of partial matching and examples aligns with the schema's search_term description but adds no new semantic information. Baseline of 3 is appropriate since schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches ServiceNow tables by name or label, queries the sys_db_object table, and provides concrete use cases. It distinguishes itself from sibling lookup tools by specifying the target resource (tables) and the underlying system table. This is a specific verb+resource definition with clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use this tool to' section provides four explicit scenarios, including verifying table existence before query_table, discovering internal names, finding related tables, and checking hierarchy. While it doesn't explicitly name alternative tools, the scenarios imply when this tool is appropriate. This is clear contextual guidance, though slightly lacking in explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint and openWorldHint annotations, the description adds valuable behavioral details: newest-first ordering, callable repeatedly for new entries, and return content. It does not mention rate limits or auth, but the read-only nature is already annotated, making this a solid 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is six sentences, front-loaded with the core purpose, then practical use cases and table selection. Every sentence adds value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only log query tool, the description covers purpose, usage, result structure, ordering, and table distinctions. With schema covering all parameters and annotations declaring safety, there are no critical gaps, making it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage with clear descriptions, enums, defaults, and an example. The description adds little beyond the schema (only the table selection guidance is partially redundant). Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries the ServiceNow system log (syslog) to check errors, warnings, and debug output, listing returned fields and ordering. It is specific and distinct from generic query tools, fulfilling the 'verb+resource' criterion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides concrete use cases (monitoring script execution, post-deployment checks, debugging), explains that it can be polled, and distinguishes between the syslog and syslog_app_scope tables. It does not explicitly name alternatives or when-not-to-use, so it misses the top tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by stating that the test 'runs on the instance' and that the tool 'waits for it to complete before returning the result,' plus it lists return fields. Annotations already convey destructive/read-only hints, so this extra disclosure is valued. It doesn't warn about side effects, but the destructiveHint already covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences cover the purpose, execution behavior, and return values, followed by a one-sentence usage guideline. Every sentence contributes new information with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, execution behavior, return values, and usage context. With no output schema, the description adequately specifies what the agent can expect, and the sibling context clarifies the difference from suite execution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both instance and test_sys_id fully described. The description adds no new parameter-level meaning beyond what the schema provides, so it meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a single ServiceNow ATF test by its sys_id', which is a specific verb and resource. It distinguishes from sibling tools like run_atf_test_suite (single vs suite) and find_atf_tests (finding vs executing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The final sentence explicitly says 'Use this tool when the user wants to run a specific ATF test and see its results,' providing clear usage context. It does not mention exclusions or alternatives, but the sibling name run_atf_test_suite implies when to use the suite variant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false). The description adds the key behavioral detail that all subsequent changes will be captured in the set, which is critical context beyond what annotations provide. It does not cover permissions or external side effects, but for a session-scoped tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core verb and resource, and every word adds value. No wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with fully documented parameters and no output schema, the description, annotations, and schema together provide sufficient context. The behavior is straightforward and scoped to the session, so no additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all three parameters have descriptive text. The tool description adds no additional meaning beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'set' with a clear resource 'active update set' and a consequence ('All changes will be captured in this update set'), which distinguishes it from siblings like get_current_update_set and create_update_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (before making changes so they are captured in the update set), but it does not explicitly mention alternatives or exclusions. The context is clear enough for an agent to infer the use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description supplements the annotations (readOnlyHint=false) with an explicit warning that this 'creates a real service request on the instance.' This adds important context beyond the machine-readable metadata. It also explains the return value, but does not discuss failure modes, permissions, or rate limits, which would have been even more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) and well-structured. The first sentence states purpose and returns, the second provides a critical warning, and the third offers practical variable-passing guidance. Every sentence contributes valuable information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description provides sufficient context: purpose, return values, a side-effect warning, and a prerequisite suggestion. It effectively covers the essential information an agent needs to use the tool correctly, including how to handle variables and reference fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all four parameters with detailed descriptions (100% coverage). The description adds minimal new semantic information—reiterating that variables should be a key-value object and reference fields use sys_ids. This reinforces the schema but does not significantly enhance parameter understanding beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Submit a service catalog request using the ServiceNow order_now API.' It also specifies the outputs (REQ and RITM numbers), distinguishing it from sibling catalog tools like list_catalog_items or get_catalog_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance by instructing users to 'Use list_catalog_item_variables first' to understand required variables. It also warns that the tool 'creates a real service request,' implying cautious use. However, it does not explicitly mention when not to use this tool or describe an alternative for the same action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark it as read-only and open-world, and the description adds context about search groups, the default search group behavior, and how current_app affects search_all_scopes. It also notes the instance fallback to the SN_AUTH_ALIAS environment variable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an opening summary, a paragraph on search groups, and a bulleted list of use cases. It is appropriately sized for a non-trivial tool, front-loaded with the primary action, and every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the search group mechanism, result contents (record name, table, field, line numbers), and related discovery tools. It omits explicit mention of pagination or error handling, but for a read-only search tool with rich annotations and schema, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All seven parameters have schema descriptions, yielding a high schema coverage baseline of 3. The tool description adds conceptual context about search groups, helping to understand the search_group and table parameters, but it does not significantly extend parameter-specific details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for code across a ServiceNow instance, identifying scripts, business rules, script includes, and other artifacts. It uses a specific verb+resource structure and distinguishes itself from sibling tools like list_code_search_groups and query_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists concrete use cases, such as finding scripts referencing a specific API, locating business rules, and verifying deployments. It also directs users to list_code_search_groups and list_code_search_tables for discovery, but it does not explicitly state when not to use this tool or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that the article is created in 'draft' state by default and notes the HTML/wiki body options, plus an 'IMPORTANT' emphasis that it creates a new article on the instance. This adds useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—about five sentences in three short paragraphs—and front-loads the core purpose. It avoids redundancy with the schema and provides the important publish hint efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter creation tool with nested objects and no output schema, the description covers the essential creation behavior, default state, and body format choices. It does not describe the return value (e.g., sys_id of the created article), which would be helpful, but the rich schema compensates for this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already documents all parameters. The description adds practical value by noting that HTML is the more common body format, helping users choose between text and wiki fields, and by confirming the default workflow_state matches the schema default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Create a new knowledge article in a specified knowledge base,' which is a specific verb+resource statement. It also mentions the default 'draft' workflow state, distinguishing it from the sibling tool publish_kb_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to publish_kb_article for making articles visible, providing a clear alternative. It also mentions that HTML is more common than wiki, aiding format choice, though it does not explicitly exclude update_kb_article for modifying existing articles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds valuable behavioral details: it explains that log entries include errors, debug output, and cancellation reasons, and that logs may be empty depending on execution success or reporting level. It also asserts that errors/warnings are always logged regardless of reporting level, which is important context not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the core action, the second details content, and the third gives a critical caveat. Every sentence earns its place without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description clarifies what the tool returns (log entries with specific content) and when it may be empty. It also references the companion tool for a fuller picture. This is sufficient for a relatively simple read-only tool, with minor omissions like pagination behavior being covered by the limit parameter in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already having a meaningful description (e.g., context_id identifies the flow execution, limit sets max entries, order_direction sorts). The description does not add extra parameter semantics, so it stays at the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Retrieve flow execution log entries from sys_flow_log for a given context.' It specifies the source table and the input (context), and distinguishes itself from the sibling get_flow_execution_details by being the log retrieval counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool 'alongside get_flow_execution_details to get the full picture,' providing a clear alternative/complement. It also gives situational context by noting log entries may be empty for simple successes or when reporting level is NONE, and that errors/warnings are always logged.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds useful behavioral context by stating that records are lightweight and omit body content, which helps set expectations about the response without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences in the first paragraph cover purpose and filters, and a final sentence directs users to the sibling tool. No word is wasted, and important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (8 parameters, no output schema), the description adequately explains the return scope (summaries without body), filter dimensions, and how to get full content. It lacks explicit mention of pagination behavior, but limit/offset parameters are already documented in the schema. Overall, it is sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all 8 parameters. The description reinforces the filter options (knowledge base, category, workflow state, text search, encoded query) but does not add significant meaning beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists knowledge article summaries from the kb_knowledge table, using the specific verb 'List' and resource. It distinguishes itself from the sibling get_kb_article by explicitly noting it returns lightweight records without body content, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage guidance by pointing to get_kb_article when full article body content is needed, effectively stating when not to use this tool. It also enumerates common filter criteria, giving the agent clear context for when to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable context by specifying that the tool 'modifies update set membership of records on the instance', which clarifies exactly what is changed. This goes beyond the annotations and warns the user about the side effect. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, front-loaded with the primary action, followed by a necessary warning. Every sentence earns its place, and there is no redundant or verbose wording. It is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a moderately complex tool. It explains the operation, both usage modes, and the critical side effect. There is no output schema, so return values are not described, but the annotations and schema cover safety and parameter details. It does not mention edge cases like moving a record already in the target, but this does not significantly impede correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all four parameters with detailed descriptions (100% coverage). The description adds a higher-level explanation of the parameter relationships: 'move specific records by sys_id, or move all records from a source update set.' This helps the agent understand when to provide record_sys_ids versus source_update_set, adding value beyond the schema's individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Move records from one update set to another.' It identifies the specific verb 'move' and the resource 'update set records', and distinguishes between moving specific records by sys_id or all records from a source. This distinguishes it from sibling tools like clone_update_set or create_update_set, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to use the tool, explaining the two modes: moving specific records by sys_id or moving all records from a source update set. It does not explicitly mention alternatives or when not to use it, but the unique action 'move records' makes the use case obvious compared to siblings. The IMPORTANT note adds guidance on the operation's effect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond the annotations: it makes the article publicly visible and warns to ensure review before publishing. The annotations already signal mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false), but the description enriches with visibility impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main action, followed by a relevant warning. No redundancy or fluff. The IMPORTANT note earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two params and no output schema, the description is complete. It explains what happens (visible to end users) and includes a safety warning. It doesn't discuss return values or error cases, but these are not critical for this operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds semantic meaning by stating the sys_id must be for a 'draft' article. This is a meaningful constraint not explicitly in the schema. The instance parameter is well covered by the schema description already.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Publish a draft knowledge article by setting its workflow_state to published.' This clearly distinguishes it from sibling tools like create_kb_article, update_kb_article, and get_kb_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for publishing draft articles and making them visible. It doesn't explicitly name alternatives or say when not to use it, but the 'IMPORTANT' note about review before publishing gives practical guidance. This is one step below explicit when/when-not/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, and the description reinforces this with 'IMPORTANT: This modifies code on the ServiceNow instance' and the requirement that the record must exist. This adds meaningful context beyond the annotations by clarifying the operational impact and precondition, even if it doesn't detail all 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-organized: a clear opening sentence, an important warning, and a compact list of supported types. Every sentence adds crucial information without redundancy, making it easy for an agent to parse and act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no output schema), the description covers key behavioral aspects: it modifies code, requires an existing record, and specifies allowed script types. It omits details like error handling or response format, but these are not essential for selecting and invoking the tool correctly, especially with the sibling pull_script providing complementary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all four parameters with descriptions, providing a high baseline. The description adds value by enumerating supported script types with friendly names (e.g., 'Script Include', 'Business Rule') and explaining that the record is found by name in the appropriate table, which clarifies script_name and script_type semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Push a local script file to a ServiceNow instance, updating the script field on the matching record.' It identifies the specific verb (push), resource (local script file), destination (ServiceNow instance), and action (update script field), and distinguishes itself from the sibling pull_script by focusing on the push/update direction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes that the record must already exist and that this tool updates, not creates, which frames when to use it. It also lists supported script types, providing useful selection context. However, it does not mention alternatives or when to prefer a different tool (e.g., execute_script), though the limitation to existing records is a clear exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explicitly warning that multiple records (workflow, version, activities, transitions) are created, which aligns with the non-readOnly and openWorld annotations. It also discloses the orchestration sequence and the id/index referencing convention, providing behavioral context that is not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose appears in the first sentence, followed by a concise bullet-like orchestration list and a short cautionary note. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main orchestration steps and important side effects, but it omits the return value (e.g., workflow sys_id), which is significant given there is no output schema. The note to 'review the specification carefully' is vague and doesn't highlight potential validation failures or required dependencies beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds the crucial rule that activities in transitions are referenced by `id` field or array index, which is not fully captured in the individual schema descriptions for `transitions` and `start_activity`. This clarifies how to use multiple parameters together, raising the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: it creates a complete ServiceNow workflow from a single specification, enumerating the orchestration steps (workflow, version, activities, transitions, optional publish). This verb+resource phrasing distinguishes it from sibling tools like batch_create_records or execute_flow, which target different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening sentence establishes a clear context: use this when you need to create a complete workflow from a specification rather than building its components individually. However, it does not explicitly state when not to use it or name alternative tools, so it lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds meaningful context by explaining that it returns only direct relationships and accepts direction filters, which is not obvious from the annotations. It also clarifies that the sys_id can come from any CI class table. It does not disclose return format or pagination, but for a read-only tool with annotations covering safety, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs, with the first sentence stating the core purpose and the second giving use cases. The second paragraph adds practical parameter guidance. Every sentence earns its place; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, 1 required) and strong schema coverage, the description is complete enough. It covers purpose, use cases, and parameter details, while annotations handle safety. Although there is no output schema, the description hints at return directions appropriately, making it sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for all 5 parameters, each with descriptions. The description adds value beyond the schema by providing concrete examples of relationship types (e.g., 'Depends on::Used by', 'Contains::Contained by') and clarifying that ci_sys_id can come from any CI class table. This enhances understanding without repeating schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Get direct relationships of a CMDB Configuration Item (CI).' It also specifies the return directions (upstream, downstream, or both) and distinguishes itself from the sibling tool 'traverse_cmdb_graph' by emphasizing 'direct' relationships. The use cases (impact analysis, dependency mapping, topology) further clarify intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: 'Use this for impact analysis, dependency mapping, and understanding CI topology.' However, it does not explicitly mention alternatives or when not to use it, such as comparing with 'traverse_cmdb_graph' for indirect relationships. The guidance is present but not fully exclusionary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: it lists possible states (QUEUED, IN_PROGRESS, etc.) and describes the polling pattern. It doesn't detail error responses for invalid context IDs, but annotations already cover the read-only 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. Every sentence contributes value: the initial query statement, the usage context, the state enumeration, and the typical workflow pattern. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status-polling tool, the description is complete. It lists all possible states and suggests next steps (get_flow_outputs on COMPLETE, get_flow_error on ERROR). No output schema exists, but the description covers what the agent needs to know about the return value and workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (instance and context_id) are already fully described in the input schema. The description does not add additional parameter semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Query the current status of a flow execution by its context ID.' It specifies the resource (flow execution status) and the key input (context ID), distinguishing it from sibling tools like get_flow_outputs and get_flow_error.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: 'Use this to poll background flow executions started with execute_flow, execute_subflow, or execute_action in background mode.' It also provides a typical pattern with alternatives: 'once COMPLETE, call get_flow_outputs. If ERROR, call get_flow_error.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe read operation. The description adds behavioral context by explaining what search groups are and that each instance typically has a default group. It does not contradict annotations and provides meaningful domain context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear first sentence stating purpose, followed by a short explanatory paragraph, and a final sentence with precise cross-tool usage. Every sentence earns its place with no redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description provides sufficient context: what search groups are, default behavior, and how to use the results with related tools. It covers all necessary operational knowledge for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the two parameters (limit and instance), so the schema already fully documents them. The description does not add further parameter-level meaning beyond the schema, but it does contextualize the output fields (name, sys_id) in relation to other tools. Overall, it meets the baseline without adding extra parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists code search groups on a ServiceNow instance, using a specific verb and resource. It distinguishes itself from related sibling tools like code_search and add_code_search_table by explaining how its output is used as inputs to those tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: the group `name` should be used as the `search_group` parameter in `code_search`, and `sys_id` when adding tables via `add_code_search_table`. This clearly instructs when and how to use the tool's results, effectively differentiating it from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, setting a low bar. The description adds meaningful behavioral context by listing the returned fields and highlighting the filtering capabilities (prefix, scope, extendable-only), which go beyond the annotations. It does not mention side effects (none expected) or pagination, but the schema covers limit/offset. Overall, it enriches the behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: the first states purpose and output, the second differentiates from a sibling, the third gives usage direction. It is tightly written with no fluff, and the key information is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Combined with the schema (which fully documents all 7 parameters with descriptions) and annotations (readOnly, openWorld), the description provides complete context for an agent to make an informed call. It covers the tool's purpose, return value fields, use cases, and relationship to a sibling tool. No critical information is missing for a read-only listing function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add significant semantic meaning to parameters; it merely rephrases 'name_prefix', 'scope', and 'extendable_only' as 'prefix filters, scope filters, and extendable-only mode' in the usage guidance. This is helpful for context but does not add detail beyond the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List tables on a ServiceNow instance with optional filtering.' It includes the specific resource (tables on an instance) and the return fields (name, label, parent class, scope, extendable). It also distinguishes itself from the sibling 'lookup_table' by contrasting filtering approaches, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Unlike lookup_table (which searches by name or label keyword), this tool supports browsing with prefix filters, scope filters, and extendable-only mode. Use this to discover tables in a specific scope or browse tables by naming convention.' This tells the agent when to choose this tool over an alternative and gives concrete use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds critical behavioral details: the dry-run mechanism, permanence of deletion, and the 'cannot be undone' warning. This significantly enhances an agent's understanding of the tool's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core action, and each sentence serves a purpose. The prominent safety warning is essential and effectively communicates the destructive nature without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature and absence of an output schema, the description covers all essential aspects: the operation, dry-run workflow, and irreversible consequences. It provides sufficient guidance for an agent to invoke the tool safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with detailed descriptions for all five parameters including the confirm semantics. The description reinforces the confirm behavior but does not add substantial new meaning beyond the schema's already thorough parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Find records matching an encoded query and delete them all.' This uses a specific verb and resource, highlighting the scoped deletion, and distinguishes it from sibling query/update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for safe use, emphasizing the dry-run mode and instructing to 'Always run a dry-run first to verify the match count before committing.' However, it does not explicitly mention alternatives or exclusions, which prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that this is a MUTATIVE, LONG-RUNNING operation that blocks until completion or timeout, adding meaningful detail beyond the annotations (which only mark it destructive and non-idempotent). It also mentions the default timeout of 30 minutes, providing crucial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and every sentence provides distinct value: action/resource, behavioral caveat, and usage context. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's mutative and long-running nature, the description covers expected behavior (blocking), timeout, and typical use case. However, there's no output schema, and the description doesn't explicitly state what the tool returns after completion (e.g., success status, installation logs), leaving a minor gap in expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for every parameter, so the schema carries the heavy lifting. The description adds value by explaining the overall blocking/timeout behavior and referencing list_company_apps to find scope and sys_id, which indirectly clarifies the purpose of key parameters. However, it doesn't introduce new parameter-specific details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Install') and identifies a precise resource: applications from the company's ServiceNow application repository via the CI/CD API. It also distinguishes from sibling tools like install_store_app by specifying the company repository rather than the store, making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool: 'Typically used for deploying custom applications across instances (e.g., dev -> test -> prod).' It also directs users to a related sibling tool (list_company_apps) for finding required parameters, which serves as an implicit prerequisite. It doesn't explicitly state when not to use it, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already indicate destructiveHint and readOnlyHint false, the description significantly expands on the behavioral profile: it explicitly labels the operation as 'MUTATIVE, LONG-RUNNING' and notes it 'blocks until installation completes or times out (default: 30 minutes).' It also discloses that installation adds tables, scripts, and configuration, and warns about capacity/entitlements—all beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, an 'IMPORTANT' section, and a closing guidance line. It is somewhat longer than strictly necessary, but every sentence adds value—covering mutability, timeout, prerequisites, and discovery. The front-loading of key traits (mutative, long-running) is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutative, long-running install operation) and absence of an output schema, the description is thorough. It explains what happens, how long it blocks, prerequisites (capacity, entitlements), and how to find installable apps. It does not explicitly describe the return value, but for a blocking operation with no output schema, the behavioral disclosure is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all five parameters, so the baseline is 3. The description adds high-level context (e.g., 'Use get_app_details to see available versions') but does not materially increase per-parameter meaning beyond what the schema already provides. It does reinforce connection to discovery tools, but that is more usage guidance than parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Install a ServiceNow store application on the target instance.' It specifies the resource (store application) and target (instance), and distinguishes from siblings like install_from_app_repo (different source) and update_store_app (update vs install).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Use search_store_apps with tab_context 'available_for_you' to find apps available for installation.' It also recommends reviewing app details with get_app_details and testing on sub-production, effectively guiding the agent through prerequisites and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states this is a MUTATIVE, LONG-RUNNING operation that blocks until publishing completes or times out (default: 30 minutes). This adds significant context beyond the annotations (readOnlyHint=false, destructiveHint=true), including blocking behavior and configurable timeout, which is highly valuable for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with the core action in the first sentence, followed by critical behavioral warnings, then the benefit, and finally a helpful prerequisite pointer. Every sentence earns its place with no fluff, and it is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (long-running, mutative, 6 parameters) and absence of an output schema, the description covers purpose, behavioral implications, blocking/timeout, and prerequisite. It does not mention what the return value or response looks like on success/failure, which would be useful for an agent but does not undermine overall completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for all six parameters, so the baseline is 3. The description goes beyond the schema by advising to use list_company_apps or lookup_app to find the required scope and sys_id, giving practical guidance on how to obtain parameter values. This added value warrants a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool publishes an application to the company's ServiceNow application repository using the CI/CD API, and explains the effect: making the application version available for installation. This specific verb+resource combination distinguishes it from siblings like install_from_app_repo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (publishing an app to the company repo) and gives a concrete prerequisite: use list_company_apps or lookup_app to find scope and sys_id. However, it does not explicitly contrast with alternatives or state when not to use it, slightly missing the top tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds critical behavioral context: the dry-run mode, confirm=false default behavior, and the warning that confirm=true modifies records. This goes beyond structured annotations by disclosing the safety mechanism and the irreversible nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight paragraphs, no wasted words. The main action is stated first, followed by the critical safety information. The important warning is bolded for emphasis, making it effective and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description covers the essential workflow: dry-run first, then execute. It hints at the return value (match count) and warns about modifications. It omits details like limit behavior or instance fallback, but those are fully documented in the schema, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the confirm parameter's role in dry-run vs. execution, which is not fully captured by the schema's field description. It also clarifies the 'update them all' semantics for limit, though not in detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Find records matching an encoded query and update them all with the specified data,' which clearly states the verb (update), resource (records matching a query), and scope (all matches). It also distinguishes itself from siblings like query_table (read-only) and query_delete_records (delete) by focusing on updating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Always run a dry-run first' and explains the confirm flag's role in controlling execution. It does not explicitly name alternatives or exclusions, but the dry-run-first instruction strongly implies the safe usage pattern for this mutation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond the annotations: it runs the flow in its current saved (draft) state and uses the ProcessFlow REST API endpoint. It also notes that a context ID is returned for polling. While the destructiveHint annotation warns of possible side effects, the description doesn't explicitly elaborate on potential data modifications, but the draft-state emphasis and API detail add meaningful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a bit long but every sentence contributes: it states the core function, primary use case, comparison with execute_flow, API details, parameter guidance, and next steps. The logical flow is clear, and no filler is present. It could be slightly tightened, but it is well-structured and front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (testing flows), the description covers all essential aspects: what it does, when to use it, how to invoke it with parameter examples, what it returns (context ID), and what to do next. There is no output schema, but the description explicitly guides follow-up polling and retrieval, making it complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema descriptions cover 100% of parameters, the tool description adds extra meaning by explaining output_map with a concrete example for record-triggered flows and detailing flow_id formats. It also hints at the scope auto-resolution behavior, which supplements the schema's brief description. This goes beyond simply restating parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Test a ServiceNow Flow Designer flow without requiring it to be published.' It uses a specific verb ('test'), names the resource ('Flow Designer flow'), and distinguishes itself from execute_flow by noting it works on unpublished drafts. This is a strong, specific statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly positions test_flow as 'the PRIMARY tool to use when building and iterating on a flow' and contrasts it with execute_flow, which requires a published flow. It also recommends follow-up tools (get_flow_context_status, get_flow_outputs, get_flow_error) and provides example input for record-triggered flows, giving clear when-to-use and how-to-proceed guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it warns that the operation is MUTATIVE, LONG-RUNNING, blocks until completion or timeout (default 30 minutes), and may alter behavior, modify tables, affect customizations, and overwrite customizations. This goes well beyond the destructiveHint annotation and provides critical risk information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a brief opening, a bulleted list of warnings, and a practical usage tip. Every sentence earns its place, and the formatting improves readability without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers the mutation risks, blocking behavior, timeout, and discovery method. It does not describe the return value format, and since there is no output schema, this is a minor gap. However, for a mutative tool, the focus on side effects and safety is more important, and the description handles that comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds extra meaning by telling users to use search_store_apps to find the app_id and get_app_details for version, enriching the schema descriptions with practical sourcing guidance. Timeout default is also mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an installed ServiceNow store application to a newer version, using a specific verb and resource. It distinguishes from siblings like install_store_app (installing new apps) and search_store_apps (searching for updates), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use search_store_apps with tab_context 'updates' to find apps with available updates, and advises testing on a sub-production instance first. It provides clear context for when to use this tool, though it does not explicitly state when not to use it or name alternative tools beyond search_store_apps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses key behaviors: the copied flow lands in draft/unpublished state, gets a new sys_id, is independent of the source, returns the new sys_id, and prints the exact 'now-sdk transform' command. This adds substantial context that annotations alone do not provide, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it opens with the core action, then explains the rationale, lifecycle, behavior, and a practical tip. Every sentence provides value—no filler or redundancy. Front-loaded with the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers the return value (sys_id and command), the state of the copied flow, the requirement for a scope sys_id, and an alternative way to find it. It also embeds the tool within the broader lifecycle, making it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with detailed descriptions for all four parameters. The tool description reinforces important nuances (e.g., target_scope must be a sys_id, source can be OOB) but does not add significantly beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Copy an existing ServiceNow Flow Designer flow') with a clear resource and target ('into a target scoped application'). It also distinguishes this tool from siblings by framing it as the best-practice first step for modifying flows, which is unique among the flow-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'best-practice first step when you want to modify any flow', and explains why (OOB/shared flows should not be modified directly). Provides a lifecycle (copy_flow → pull → modify → push → test_flow → publish_flow) and directs users to list_scoped_apps for target_scope, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavior beyond what annotations provide: foreground mode blocks until completion, background mode returns a context ID for polling, and foreground mode will fail on flows with waiting states. It also warns that flows must be published. These are non-obvious operational constraints that significantly aid correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, distinct paragraphs for mode behavior, and highlighted IMPORTANT/NOTE sections. Every sentence serves a purpose—purpose, mode semantics, and alternatives—without redundancy. It's appropriately sized for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, dual execution modes, no output schema), the description covers all key operational aspects: how to run, polling mechanism, prerequisites, and alternative tools. It addresses the main pitfalls (wait states, unpublished flows) and sufficiently orients an agent for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter coverage with detailed descriptions (e.g., mode, quick, scope, inputs, timeout, instance, scoped_name). The tool description adds context about modes but does not materially enhance parameter meaning beyond what the schema already explains. Baseline 3 applies because the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: "Execute a published ServiceNow Flow Designer flow by scoped name." It uses a specific verb ('execute'), identifies the resource, and provides implementation detail (sn_fd.FlowAPI). It distinguishes itself from siblings by referencing test_flow and get_flow_context_status, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given for when to use this tool vs alternatives: flows with approval/wait steps MUST use background mode, and for unpublished flows, the description says to use test_flow instead. This directly addresses selection criteria and prevents misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, covering safety and dynamic results. The description adds useful context about session filtering and package existence, which helps the agent interpret the output. No contradictions or hidden side effects are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the function and scope, the second adds a valuable usage note. Information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only introspection tool, the description fully covers what it does, when to use it, and how to interpret results. Annotations handle safety and open-world aspects, and no return format is needed for a simple list view.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage, so the baseline is 4. The description introduces no parameter details, but none are needed. It focuses on the tool's purpose and usage context, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') with a clear resource ('which tool package this session is running and what other packages exist'). It distinguishes this tool from the many sibling data-manipulation tools by focusing on package inventory rather than records or operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: when a capability is missing, suggesting the tool may exist but is filtered out. It clarifies the expected interpretation (a different MCP_TOOL_PACKAGE) and prevents confusion with a missing feature. This is strong actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![now-sdk-ext-mcp MCP server](https://glama.ai/mcp/servers/sonisoft-cnanda/now-sdk-ext-mcp/badges/card.svg)](https://glama.ai/mcp/servers/sonisoft-cnanda/now-sdk-ext-mcp)

Score Badge

Copy to your README.md:

[![now-sdk-ext-mcp MCP server](https://glama.ai/mcp/servers/sonisoft-cnanda/now-sdk-ext-mcp/badges/score.svg)](https://glama.ai/mcp/servers/sonisoft-cnanda/now-sdk-ext-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sonisoft-cnanda/now-sdk-ext-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server