servicenow-mcp-server

Server Quality Checklist

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

Latest release: v1.0.4
Disambiguation3/5
There is significant overlap between generic tools (query_records, get_record, create_record, update_record) and specialized tools (list_incidents, get_incident, create_incident, etc.). While descriptions suggest using specialized tools when available, an agent could easily be confused about which tool to call for listing incidents vs. querying the incident table.
Naming Consistency5/5
All tools follow a consistent 'servicenow_verb_noun' pattern using snake_case. Verbs like get/list/search/create/update/delete are used predictably across the set, and even compound names like get_ci_relationships follow the same structure.
Tool Count2/5
With 41 tools, this server exceeds the recommended threshold for a well-scoped tool set. While the domain is broad, many tools could be consolidated (e.g., generic CRUD already covers core record operations), making the set feel heavy and harder to navigate.
Completeness4/5
The tool surface covers major ServiceNow domains (incidents, changes, CMDB, knowledge, catalog, users, groups) plus admin and development tools. Gaps exist for problems, approvals, and knowledge article management, but generic record tools can work around these limitations.
Average 4.2/5 across 41 of 41 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the return value (number and sys_id) which is helpful beyond the annotations. It aligns with readOnlyHint=false but does not disclose potential side effects like approval workflows, validation failures, or required permissions. The annotations already cover the safety profile, so this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with the purpose first, then a list of args, then return info. It is somewhat verbose because the args list largely duplicates schema property descriptions, but given the high parameter count, it remains readable and front-loaded.
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?
For a 15-parameter create tool with no output schema, the description covers most parameters and includes the return value. However, it omits a couple of schema fields and does not clarify any type-specific requirements (e.g., emergency change validation). The tool is complex, so the description is adequate but not fully 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 description adds useful details beyond the schema, such as date format example and risk mapping. However, the risk mapping is incomplete (schema includes a 4th level, 'Very High') and two schema parameters (justification, response_format) are omitted. Schema coverage is 100%, so the baseline is 3, and the description provides marginal extra 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?
The description states 'Create a new ServiceNow change request' with a specific verb and resource, clearly distinguishing from sibling tools like create_record or create_incident. The title and tool name reinforce this.
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 explicit guidance is provided on when to use this tool versus alternatives such as create_record or update_change. There is no mention of prerequisites, exclusions, or context like change management processes.
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, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond annotations, such as supporting partial name matching ('partial name to match') and specifying the return fields (names, usernames, emails). This goes beyond the safety profile already provided, though it doesn't disclose edge-case behaviors like error handling.
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 concise, with a clear first sentence and a compact args list. However, the args list largely duplicates the schema information for limit, offset, and response_format, which is minor redundancy. It remains appropriately sized and front-loaded with the purpose.
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, strong schema coverage, and rich annotations, the description is fairly complete. It covers return values, which is important since there is no output schema. It lacks context on possible errors or behavior when no matches are found, but for a simple read-only group-member lookup, this is sufficient.
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%, so baseline is 3. The description adds the detail that group_identifier accepts a 'partial name to match', which is not stated in the schema (schema says 'Group name or sys_id'). It also summarizes pagination and response_format, but slightly less detailed than the schema. The partial-match addition increases semantic clarity.
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: 'Get all members of a ServiceNow user group.' This is a specific verb+resource combination. It does not explicitly differentiate from sibling tools, but the resource (group members) is distinct enough for an agent to understand what it does.
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?
The description provides no guidance on when to use this tool vs alternatives like list_users or get_user. It only states what the tool does, leaving the agent to infer context. No exclusions or alternative suggestions are mentioned.
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 disclose this is a write operation (readOnlyHint=false) and open-world (openWorldHint=true). The description adds conditional requirements for resolution, but does not reveal side effects, permission needs, or the nature of updates (e.g., partial vs. full overwrite). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose, followed by a well-organized args list and a return statement. It is concise and wastes no words, though the args list partially duplicates schema descriptions.
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?
With 13 parameters, nested objects, and no output schema, the description adequately covers core usage but provides a vague 'Updated incident details' return value. It also fails to mention the response_format parameter. The schema fills gaps, so overall completeness is adequate but not rich.
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 each parameter already described. The description adds some value by restating state mappings and the required-when-resolving condition, but it omits several schema parameters (impact, urgency, comments, work_notes, response_format) and provides no extra detail beyond the schema for most fields.
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 'Update' and resource 'a ServiceNow incident', listing specific fields like state, assignment, priority, and 'any field'. It distinguishes itself from generic alternatives like servicenow_update_record by being incident-specific and enumerating relevant fields.
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 clear context for updating incidents and includes conditional usage guidance (resolution_code and resolution_notes are required when resolving). It does not explicitly name alternatives, but the incident-specific focus provides enough direction for the agent.
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 idempotentHint=true, covering safety. The description adds context that the response includes implementation, backout, and test plans, which is useful beyond the annotations but does not disclose other potential behaviors like error handling or output size.
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 an Args section and Returns section, and the main prose is concise. However, the Args list largely duplicates the input schema, adding a small amount of 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 read operation with 2 parameters and no output schema, the description adequately covers what the tool returns (complete change request including planning fields). It lacks mention of error scenarios or rate limits, but these are not critical for a basic get operation.
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 identifier and response_format are fully documented in the schema. The description merely repeats the identifier meaning without adding new semantics, providing no extra value 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 'Get full details of a ServiceNow change request by number (CHG...) or sys_id', specifying the exact resource (change request), the verb (get), and the scope (full details including specific plan fields). This distinguishes it from generic get_record and list_changes sibling 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 gives clear context on when to use the tool: when you need full details of a single change request, identified by number or sys_id. It doesn't explicitly list alternatives or exclusions, but the specific scope makes the usage obvious next to siblings like list_changes or get_record.
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, idempotentHint=true, and destructiveHint=false, so the read-only behavior is covered. The description adds value by specifying the return payload: 'Complete incident details including description, work notes, and all fields', which goes 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loads the core purpose. The Args section is somewhat redundant with the schema, but it is brief and does not contain filler. Overall, it is well-structured and no sentence 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?
For a simple two-parameter read operation with no output schema, the description sufficiently states the return content and scope. It does not address error behavior (e.g., incident not found), but this is not a critical gap for a straightforward getter. The tool is adequately described.
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 both parameters have detailed descriptions. The description's 'response_format: Output format' is less informative than the schema's explanation of markdown/json. The identifier example is already in the schema, so the description adds 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 the tool gets 'full details of a single ServiceNow incident by number (e.g., INC0012345) or sys_id', specifying both the verb and resource. This distinguishes it from list tools like servicenow_list_incidents and generic get_record by focusing on a single incident.
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 word 'single' implies this is for one incident, but the description does not explicitly name alternatives like servicenow_list_incidents for multiple incidents or servicenow_get_record for other tables. The context is implied by the naming and namespace, but there is no explicit when-to-use or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds only minimal behavioral context (e.g., 'Returns: The record's field values') and does not discuss error cases, permissions, or rate limits. This is acceptable given strong annotations, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with Args, Returns, and Examples, making it easy to scan. Every sentence is purposeful, though the Args section partially duplicates the schema descriptions, preventing a perfect score.
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-by-sys_id tool, it includes purpose, parameter explanations, and examples. It lacks explicit output schema or error handling, but given the strong annotations and comprehensive schema, it is sufficiently 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.
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 largely restates the schema parameter descriptions (e.g., 'table', 'sys_id', 'display_value') and provides examples, but it does not add meaningful extra context beyond what the schema already documents.
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 a single ServiceNow record by sys_id from any table,' which is a specific verb+resource+scope. It distinguishes itself from specialized getter tools like servicenow_get_incident by explicitly supporting any 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 implies usage via 'any table' and provides concrete examples for incident and CI records. However, it does not explicitly mention alternatives like the specialized getter tools or when to prefer this generic version over them, so it lacks explicit 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?
Annotations already indicate a mutating (readOnlyHint=false) and non-destructive (destructiveHint=false) operation. The description adds the crucial detail that only specified fields are changed (PATCH semantics), and explicitly mentions the return value. This goes beyond the structured 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise lead sentence, a bulleted Args list, a Returns line, and two illustrative examples. It is appropriately sized and front-loaded, with no redundant content; each section 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?
Given 4 parameters, high schema coverage, and no output schema, the description provides sufficient context: the update semantics, the return value, and typical use cases. It does not over-explain but is complete enough 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 coverage is 100%, so the schema documents all parameters. The description adds example values for key parameters (e.g., data={"state":"4"}) that illustrate usage but does not redefine parameter semantics. This meets the baseline for high schema coverage with marginal additional 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?
The description clearly states a specific verb ('Update') and resource ('existing ServiceNow record by sys_id') and specifies the HTTP method (PATCH). It distinguishes the generic update tool from specialized siblings like update_incident and update_change by focusing on arbitrary table/sys_id combinations. Examples reinforce 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the PATCH semantics and examples (e.g., closing a problem, reassigning a task), but it does not explicitly state when to prefer this generic tool over specialized siblings like servicenow_update_incident or servicenow_update_change. There is no mention of exclusions or 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 readOnly, idempotent, and non-destructive, so the description adds value by disclosing that HTML is stripped to plain text and that metadata is returned. This provides behavioral context beyond the safety annotations, though it does not cover error handling or authentication specifics.
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 with the main action, followed by concise parameter docs and a return statement. Every sentence contributes, with no fluff or repetition of annotations.
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 tool with good annotations, the description covers purpose, parameters, and return format (plain text with metadata). It lacks details on failure behavior or specific metadata fields, but those are minor in the context of a straightforward fetch operation.
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's parameter explanations (identifier format, response_format output) largely mirror the schema and add no extra semantic meaning beyond what is already present.
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 fetches the full content of a knowledge base article by KB number or sys_id, which is specific and distinguishes it from generic get_record or search_knowledge siblings. The verb 'Get' and resource 'knowledge base article' are explicit, with identifier format details.
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 when full article content is needed, but it does not explicitly mention alternatives or exclusion criteria. A sibling tool like search_knowledge likely exists for finding articles, so explicit guidance such as 'use this after search_knowledge to retrieve full content' would improve this dimension.
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 a mutation (readOnlyHint=false) and not idempotent. The description adds useful behavioral details such as return values (created REQ and RITM numbers) and the need to get variables from a sibling tool. However, it does not disclose potential side effects like triggering approvals, validation failures, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and a Tip. It is concise, front-loaded with the action, and every section adds value without unnecessary prose. The omission of response_format in Args is minor because the schema covers 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?
For a 5-parameter tool with no output schema, the description covers the essential operational aspects: required parameters, defaults, return identifiers, and a workflow prerequisite. It does not explain error cases or further approval steps, but the combination of schema (for parameters) and description (for workflow) is largely 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 baseline is 3. The description adds some context beyond the schema, such as clarifying requested_for defaults to the current user and pointing to servicenow_get_catalog_item for variable requirements. Yet it omits response_format from the Args list, and most parameter meaning is already present in 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 and resource: 'Submit a service catalog request using the ServiceNow Service Catalog API.' It clearly distinguishes this tool from sibling record/change/incident tools by naming the catalog request domain and mentioning return values REQ/RITM.
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 and a concrete prerequisite tip: 'First use servicenow_get_catalog_item to see required variables before submitting.' This guides when to use the tool, though it does not explicitly state when not to use it or name alternative tools for exclusion.
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 non-read-only, non-destructive operation. The description adds value by stating the return format ('Returns: Created incident with number and sys_id') and highlighting the flexible 'additional_fields' parameter, which aligns with the openWorldHint. It does not contradict annotations, though it omits potential side effects like notifications or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by a well-structured argument list and return note. It is somewhat redundant with the schema but remains appropriately sized for 12 parameters; every listed item conveys some additional context, such as examples or required-field designation.
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 complexity, the description is complete: it identifies the required parameter, enumerates all optional parameters with meaningful examples, and states the return value. It lacks explicit guidance on when to use this tool over alternatives and does not mention error scenarios, but those are not essential for a create operation with exhaustive schema coverage.
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 extra value by providing concrete category examples ('network', 'hardware', 'software', 'inquiry') and clarifying short_description as 'One-line summary' and caller_id as 'sys_id or username of the caller/requester'. These details go slightly beyond schema descriptions, aiding correct parameter selection.
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 'Create a new ServiceNow incident,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like servicenow_update_incident or servicenow_create_record. It unambiguously states the tool's primary 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?
The description implies when to use the tool (to create an incident) but provides no explicit guidance on alternatives or exclusions. It does not mention that generic record creation should use servicenow_create_record, nor does it state when not to use this tool. The sibling context makes the purpose clear, but there is no direct usage instruction.
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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable details like the 50 unique CI visit limit to prevent runaway traversal and the return format. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, parameter list, return description, and examples. It is appropriately sized for the tool's complexity, and every section adds value, though the examples could be seen as slightly redundant with the parameter descriptions.
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 no output schema, the description adequately describes the return value (relationship tree with CI names, types, and relationship types) and includes important constraints like the 50-CI limit. It covers all parameters and usage patterns, making it sufficient for an agent to 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 already fully describes all parameters (100% coverage), including enums and defaults. The description repeats these but adds practical examples that illustrate parameter usage. No significant new semantics beyond schema, so 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 traverses CMDB CI relationships from a starting configuration item, with specific verbs and resource. It distinguishes from sibling tools by focusing on relationship traversal rather than single-record lookup or search.
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 usage context through examples (e.g., 'What does this server depend on?') and direction/depth semantics, but does not explicitly mention alternatives or when not to use this tool. Still, the context makes appropriate use clear.
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 idempotentHint=true, so the safety profile is covered. The description adds context by noting the data comes from sys_dictionary and detailing the returned fields, but it does not disclose potential edge cases (e.g., nonexistent table) or permissions, which would add further value 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with intro, Args, Returns, and Examples sections, making it easy to scan. The Args block somewhat duplicates schema descriptions, but the examples and return-value summary earn their place, resulting in a minor deduction for 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 properly explains return fields and provides practical examples. It covers the essential context for a schema-introspection tool, though it could mention behavior for invalid table names or large result sets. Overall, it is sufficiently complete for the tool's complexity.
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 meaningful examples for table and filter_type, and clarifies include_inherited as 'own fields only,' which goes slightly beyond the schema's description. This added nuance justifies 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 'Inspects the field definitions (schema) of any ServiceNow table,' naming a specific verb and resource. It distinguishes itself from sibling record/query tools by focusing on schema introspection and explicitly mentions the sys_dictionary source.
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 use cases through examples ('Explore incident fields,' 'Find all reference fields on change_request,' 'Inspect a custom table'), making the intended context evident. It does not explicitly mention when not to use it or name alternative tools, but the examples and 'any table' scope offer adequate 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 and idempotentHint, and the description adds useful behavioral context by specifying the return payload ('Full user record including sys_id, name, email, department, manager, roles') and demonstrating flexible lookup identifiers. It does not contradict annotations and provides extra value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured into Args, Returns, and Examples sections with no fluff. Every sentence adds value, and the examples provide concrete usage clarity without unnecessary length.
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 lookup tool with full schema coverage and no output schema, the description is complete. It states the return format, covers all lookup methods, and provides examples. No additional context is necessary for the agent to invoke this 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 coverage is 100% with each parameter described, so the baseline is 3. The description adds example values for the identifier parameter and repeats the response_format options, but these add marginal value over the schema's own descriptions. It does not significantly deepen 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 'Get a ServiceNow user by username, email, or sys_id' with a specific verb and resource. It distinguishes itself from sibling tools like list_users or get_record by focusing on single-user lookup by identifier and providing examples.
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 through its explicit lookup-by-identifier scope, but it does not explicitly state when to use this tool over alternatives like servicenow_list_users or when not to use it. No exclusions or alternative tool references are provided, so it falls short of clear 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 establish this as a read-only, idempotent operation, and the description complements this by revealing return fields (test names, descriptions, sys_ids) and highlighting the purpose of sys_ids. It also discloses default behaviors for suite_only and active_only, adding value 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose statement and organized with an Args list and Returns section. Some redundancy exists because the Args list mirrors the schema, but the Returns note about sys_ids is valuable and keeps the description appropriately sized for a tool with six parameters.
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 partially compensates by explicitly listing return fields and connecting them to the sibling run tool. It also covers pagination and defaults. Missing details like ordering or error conditions are minor for a read-only list tool, so the description is reasonably 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 baseline is 3. The description's Args block largely repeats the schema without adding new semantics, though it does clarify that suite_only defaults to false and active_only defaults to true. This adds minimal extra meaning beyond the schema, so it aligns with 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 'List Automated Test Framework (ATF) tests and test suites available on the instance,' using a specific verb and resource that clearly identifies the tool's function. It distinguishes itself from sibling tools like servicenow_run_atf_test and other list tools by focusing solely on ATF tests.
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 by stating it returns 'sys_ids (needed for servicenow_run_atf_test)', which explicitly indicates when this tool should be used as a precursor to running an ATF test. However, it does not mention exclusions or alternatives, so it falls short of fully explicit 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?
The description adds significant behavioral details beyond the annotations: requires ATF plugin and role, asynchronous execution, results may not be immediately available, and advice to check sys_atf_result table. This enriches the agent's understanding of the tool's side effects and limitations, going beyond the simple hints in annotations.
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 statement, a concise prerequisites line, a bulleted argument list, and a critical asynchronous note. It is slightly verbose but every section earns its place, making it easy to scan and understand.
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 running ATF tests, the description covers essential context: preconditions, argument details, return value (pass/fail with step results), and asynchronous behavior with fallback guidance. While it does not detail error specifics or result interpretation, it is sufficiently complete for an agent to invoke the tool effectively.
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 mostly repeats the schema's parameter descriptions, though it adds a useful hint that sys_id comes from servicenow_list_atf_tests and clarifies response_format output. These additions are marginal and do not substantially compensate 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: 'Execute an ATF test or test suite and return the result.' This specific verb+resource combination distinguishes it from sibling tools like servicenow_list_atf_tests, 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 provides clear usage context: it mentions prerequisites (plugin and role) and the source of the sys_id ('from servicenow_list_atf_tests'). It also notes the asynchronous execution and fallback result table, giving practical guidance. However, it does not explicitly state when not to use this tool or compare it to alternative 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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already establish this as a safe read operation. The description adds behavioral context such as default active-only filtering, per-type limits, and returning script previews, which 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (summary, Args, Returns, Examples) and front-loaded with a strong first sentence. While it repeats some schema details, the examples and artifact type table justify the length. It stays focused and scannable.
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 six parameters and no output schema, the description covers the return format ('name, type, table, and script preview'), provides usage examples, and explains all major options. It could mention pagination or interaction between filters, but completeness is adequate for this search 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% with detailed descriptions for all six parameters. The description's Args section largely repeats schema information but adds the mapping of artifact type enums to actual table names (e.g., 'business_rule' → sys_business_rule) and the response_format explanation. This is marginal value, 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 searches across specific ServiceNow developer artifacts (business rules, script includes, client scripts, UI actions, rest operations) by name or script content. This specific verb+resource combination distinguishes it from sibling search tools like search_ci or search_knowledge.
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 the tool through examples (e.g., 'Find all incident business rules') and the artifact type list. It doesn't explicitly mention alternatives or exclusions, but the artifact scope is well-defined, making it obvious when this tool is 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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context by explaining what the query parameter encodes (e.g., 'workflow_state=published') and describing return fields (title, category, author, state, view count). This goes beyond the schema and offers meaningful behavioral insight.
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 an opening summary, an Args section, Returns, and Examples. It is efficient and front-loaded. Some redundancy exists (the Args section closely mirrors the schema), but the examples and return description justify the length. Every section earns its place for a 6-parameter tool.
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 explains return values adequately. It covers all six parameters, provides examples for search scenarios, and clarifies pagination and response_format. It is complete for the tool's complexity, though it could mention fallback behavior when search_text is empty or how knowledge_base sys_ids are obtained.
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 reinforces parameter meanings with examples (e.g., search_text='VPN', query='category.labelLIKEsecurity') but does not add substantial semantic detail beyond what the schema already documents. It mainly restates the parameter purposes in a more human-readable form.
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 the ServiceNow knowledge base for articles by keyword, category, or filter. This specific verb+resource combination distinguishes it from siblings like servicenow_get_kb_article (which retrieves a single article) and servicenow_search_ci (which searches configuration items).
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 examples of when to use the tool, such as searching for 'VPN' articles, filtering by 'workflow_state=published', or by category via 'category.labelLIKEsecurity'. While it gives clear usage context, it does not explicitly state when not to use this tool or mention alternatives like get_kb_article for known sys_ids.
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, idempotentHint=true, and destructiveHint=false. The description adds context about the underlying Aggregate API and emphasizes it does 'not fetch records,' explaining server-side efficiency. It doesn't describe output details or error cases, but the annotation coverage reduces the burden.
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: a one-sentence purpose, a brief API note, an arg list, and four illustrative examples. While the arg list duplicates schema property names, the examples earn their place and the overall length is appropriate for a tool with 10 parameters. No wasted sentences.
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?
With 10 parameters and no output schema, the description is fairly complete but leaves the output structure implicit. It mentions response_format for markdown/json but doesn't describe what fields or rows the agent should expect in the response. It also doesn't clarify behavior when multiple aggregate fields are specified or no aggregate fields beyond count, though examples partially mitigate this.
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 covers 100% of parameters with descriptions, so baseline is 3. The description adds value by providing concrete example values for query, group_by, and aggregate fields (e.g., 'state!=7', 'priority=1^assignment_group=SYS_ID'), which clarify acceptable syntax beyond the schema's generic 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?
Description opens with 'Calculate COUNT, SUM, AVG, MIN, or MAX on any ServiceNow table — optionally grouped by a field.', clearly stating the specific verb (calculate), resource (ServiceNow tables), and operations. This distinguishes it from sibling tools, none of which offer aggregate statistics.
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 explains that it uses the Aggregate API 'for efficient server-side aggregation without fetching records,' implying it should be used when aggregate statistics are needed rather than raw record retrieval. It provides four concrete examples showing appropriate scenarios (e.g., counting open incidents by priority). However, it does not explicitly name alternatives like query_records for cases where raw data is needed.
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, but the description adds 'irreversible' and 'permanently removes the record,' going beyond the annotation to explain the consequence. No contradiction exists, and the caution label provides additional safety 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 compact and well-organized: action, args, returns, and warning. Each sentence serves a purpose, and the prominent destructive warning is valuable. 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 simple 2-parameter delete, it covers the core aspects: action, parameters, return value, and destructive warning. The absence of an output schema is offset by the 'Returns: Confirmation of deletion' note. It doesn't address edge cases like not-found, but that's not essential for this 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 schema already documents both table and sys_id. The description repeats the parameters without adding extra format details or usage nuances 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 states 'Permanently delete a ServiceNow record by sys_id' – a specific verb and resource. It clearly distinguishes itself from siblings like create, update, and bulk_delete by focusing on a single record deletion.
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 a clear when-not instruction: 'Use only when deletion is explicitly requested.' It implies single-record scope via sys_id but does not explicitly mention alternatives like bulk_delete for multiple records, 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 annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, so the safety profile is clear. The description adds the return payload ('table names, labels, parent classes, and scopes') and pagination grouping, which provides useful transparency beyond the annotation flags.
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 summary sentence, an Args list, Returns line, and examples. It is appropriately concise, with each section serving a purpose, though the Args duplication could be trimmed slightly to avoid redundancy with the schema.
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 lack of an output schema, the description supplies essential return-field information and examples that cover common use cases. It also provides enough context for an agent to invoke the tool appropriately with pagination and filter parameters.
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 6 parameters are described in the input schema with full coverage, and the description's 'Args' section largely duplicates schema field descriptions. The examples do illustrate typical values ('search='incident'', 'scope=x_'), but they don't add semantic information 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 'Search and list ServiceNow tables by name, label, or scope', specifying the verb, resource, and filtering capabilities. It distinguishes itself from siblings like query_records or get_table_schema by focusing on table 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?
It notes the tool is 'Useful for exploring the data model' and provides concrete examples (incident tables, custom tables, CMDB tables), which gives an agent clear context on when to use it. It doesn't explicitly mention alternatives or exclusions, but the use cases are illustrative enough for typical discovery scenarios.
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, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds context beyond the annotations by specifying what exactly is returned: 'description, category, variables/questions required to order.' This helps the agent understand the tool's output 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 extremely concise and well-structured: a one-sentence purpose, an Args block with clear parameter names, and a Returns line. Every sentence carries information, and there is no fluff or repetition of schema fields beyond what is necessary.
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 retrieval tool with strong annotations and full schema coverage, the description is sufficient. It tells the agent what the tool returns and the key parameters. The only gap is that it doesn't detail the exact structure of the response for the 'json' format, but the response_format parameter already explains that. Overall, it's complete enough for its complexity.
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 covers both parameters with descriptions, so baseline is 3. However, the description adds one key detail not in the schema: 'identifier (string): Catalog item name (partial match) or sys_id'—the 'partial match' behavior is extra semantic information. The response_format parameter is already well described in the schema, so the description's contribution is modest but meaningful.
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 full details of a service catalog item including its variables/form fields.' This is a specific verb+resource+scope, and it distinguishes from siblings like list_catalog_items (which would list multiple items) and submit_catalog_request (which orders). The inclusion of 'variables/form fields' highlights the unique value of this tool.
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—it fetches full details for a single catalog item—but does not explicitly mention when to use this tool versus alternatives. Sibling tools like list_catalog_items and submit_catalog_request are not referenced. The guidance is embedded in the tool's name and purpose, but no explicit when/when-not or alternative direction is given.
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 read-only, idempotent, open-world, and non-destructive. The description adds value by explaining that the identifier can be a 'contains' match (not just exact) and that the return includes hardware, network, OS, and relationship details. These are behavioral traits beyond the annotation flags, providing useful context for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, a concise Args list, and a Returns line. Every sentence adds pertinent information with no redundancy or filler. It avoids restating the tool title.
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 single-CI tool with no output schema, the description adequately covers input usage and return content. It mentions the full CI record including hardware, network, OS, and relationships, which compensates for the lack of an output schema. A minor gap is the lack of error behavior when no match is found, but given the openWorldHint and tool simplicity, this is acceptable.
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 covers all three parameters (100% coverage), so the baseline is 3. The description enriches semantics by noting that identifier supports 'exact match or contains' and that class_name is used 'if name is ambiguous', giving the agent a better understanding of how parameters behave in practice.
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 is explicit: 'Get detailed information about a specific CMDB configuration item by name or sys_id.' It clearly identifies the action (get), resource (CMDB configuration item), and scope (by name or sys_id). This differentiates it from siblings like search_ci (search) and get_record (generic), while the mention of class_name further narrows the use case.
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 context: you need a CI name or sys_id, and class_name helps when the name is ambiguous. However, it does not explicitly state when to prefer this tool over alternatives like search_ci or get_ci_relationships, nor does it provide exclusions. Guidance is implied rather than direct.
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=false, idempotentHint=false, destructiveHint=false, so the baseline safety profile is covered. The description adds minimal behavioral context: it mentions returning the sys_id and says 'use raw values' for data, but it does not disclose any potential side effects, required fields, or error handling. Given the annotations already cover the core safety aspects, the description adds some but not rich behavioral insight, meriting a mid-range score.
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 sections for args, returns, examples, and a note. While it repeats some schema content (e.g., response_format), the examples and exclusion note are valuable and not verbose. Every section contributes to understanding, and the main purpose is front-loaded, so it earns a strong but not perfect score.
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 a generic create tool with no output schema and 3 parameters, the description provides a clear purpose, argument explanations, return value, examples, and guidance on when not to use it. It does not cover potential validation failures or mandatory-field requirements, but the provided information is sufficient for an agent to select and invoke the tool correctly in most cases.
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% for all three parameters, so the baseline is 3. The description adds value beyond the schema by providing concrete examples (problem and task) and the guidance 'use raw values' to indicate encoding expectations, which clarifies how 'data' should be supplied. This additional context justifies a score above 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 'Create a new record in any ServiceNow table' which is a specific verb+resource+scope. It explicitly distinguishes itself from the dedicated incident and change creation tools in the note, and the examples with problem and task tables clarify its generic applicability.
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 says 'For incidents and change requests, prefer the dedicated tools (servicenow_create_incident, servicenow_create_change)' in the note. It also provides examples for problem and task, giving clear 'when to use' guidance relative to siblings. This surpasses the baseline by naming 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, idempotentHint=true, and destructiveHint=false, and the description adds the concrete data sources (sys_properties, sys_cluster_state, sys_upgrade_history) and instance name/URL. This gives the agent insight into what will be read and returned, going beyond the annotation safety hints with non-obvious implementation 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 front-loaded with the main purpose, uses a clear bulleted list for return content, and every line is informative without filler. It is concise yet complete for this tool's scope.
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 having no output schema, the description explicitly lists the four categories of returned data, making the expected output clear. The tool is a simple read-only health snapshot, and the description covers what, when, and how to use it, leaving no significant 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 for the only parameter (response_format) is 100%, so the description doesn't need to add much. The description reinforces that no arguments are required and mentions output formats in the returns list, but this largely duplicates 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 opens with 'Return instance version, cluster nodes, recent upgrades, and key configuration properties,' which is a specific verb+resource statement that clearly differentiates from siblings that handle records, incidents, or catalog items. It unambiguously identifies this as an instance-level health/info 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?
The description states 'No arguments required — returns a health snapshot of the connected ServiceNow instance,' which provides clear context for when to call it. It doesn't explicitly exclude alternatives, but the scope is self-evident given the sibling 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 indicate read-only, open-world, and idempotent behavior, so the bar is lower. The description adds useful context by explaining the default non-closed filter, the encoded-query syntax, and the returned fields, going beyond what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose first, then argument bullets, common queries, and return statement. It avoids fluff, though some parameter details duplicate the schema descriptions.
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 list-with-filters tool, it covers defaults, query syntax, and common use cases, and there is no output schema so the return fields are stated. It could additionally discuss pagination edge cases, but limit/offset parameters and examples make the behavior sufficiently clear.
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 describes all four parameters with 100% coverage, so the baseline is 3. The description adds practical value with common query examples and clarifies pagination grouping, which goes beyond the schema's individual 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 first sentence states 'List ServiceNow change requests with filters' using a specific verb and resource. This distinguishes it from related sibling tools like servicenow_get_change (single record) or servicenow_list_incidents (different resource).
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 and includes several concrete use-case examples (emergency changes, scheduled changes, approvals). It does not explicitly name alternatives, but the filtered-list purpose is sufficiently clear from the examples and resource name.
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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: query syntax, default behavior (empty = all open incidents), supported response formats (markdown/json), and return fields (state, priority, assignment, timestamps). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for args, common query examples, and return value. It is somewhat lengthy but every line adds useful information given the complexity of ServiceNow query syntax. It is front-loaded with the purpose statement, making the tool's role immediately clear.
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 (query language, pagination, output formats) and lack of an output schema, the description covers the essential operational details: query construction, defaults, limit/offset behavior, response format selection, and the fields returned. It does not cover error handling or authentication, but for a read-only, well-annotated list tool, this is sufficient.
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 baseline is 3. The description adds significant meaning beyond the schema, especially for the 'query' parameter, with concrete examples of encoded queries (e.g., 'priority<=2^state!=7^state!=6') and clarification that empty means all open incidents. This extra guidance helps the agent construct valid queries, exceeding mere schema repetition.
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 'List and search ServiceNow incidents with filters,' using a specific verb ('list and search') and resource ('ServiceNow incidents'). It clearly distinguishes from siblings like get_incident (single incident) and query_records (generic table query) by focusing on incident listing and providing incident-specific query examples.
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: for listing/searching incidents with filters. It includes common query examples and notes that empty query returns all open incidents. However, it does not explicitly state alternatives or exclusions (e.g., 'use servicenow_get_incident for a single record'), so it misses the top-tier criteria for explicit when/when-not 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by detailing the return structure ('Log entries with timestamp, level, source, and message'), the log level numeric mapping (0=Debug, 1=Info, 2=Warning, 3=Error), and default behaviors (default level warning, since_minutes 60). This context goes beyond what annotations provide and clarifies the tool's behavior.
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-organized with clear sections (Purpose, Args, Log levels, Returns, Examples). It is slightly verbose due to the extra 'Log levels' section that partly duplicates the level parameter explanation, but the structure and examples earn their place. The core purpose is front-loaded in the first sentence, and the examples are highly useful for an AI agent.
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 absence of an output schema, the description appropriately explains return values ('Log entries with timestamp, level, source, and message'). It covers all 7 parameters implicitly through the Args list and examples, including pagination (limit/offset) and response_format. It does not discuss potential auth or rate limits, but for a read-only query tool with strong annotations and a clear description, it is sufficiently complete for an agent to use it 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?
Schema coverage is 100%, so the baseline is 3. The description adds domain-specific meaning by giving examples for the query parameter ('level=3', 'sourceLIKEBusinessRule', 'messageLIKEError') and expanding on source with common values ('BusinessRule', 'ScriptInclude', 'Workflow'). It also clarifies the level values as strings and their numeric equivalents, which the schema lists but without the mapping. This added context helps an agent construct correct parameters.
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 'Query the ServiceNow system log (syslog table) for errors, warnings, and debug messages.' It names the specific resource (syslog table) and the verb 'Query', making it distinct from sibling query tools like servicenow_query_records which targets other tables. The purpose is immediately evident.
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 usage examples ('Recent errors → level="error"', 'Business rule failures → source="BusinessRule", level="error"', 'Logs for a specific operation → query="messageLIKEMyScriptInclude"') that illustrate when to use the tool. It does not explicitly mention alternatives or when NOT to use it, but the examples create clear context for typical use cases, which meets the 'clear context, no exclusions' level.
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 the tool as read-only, idempotent, and non-destructive, lowering the bar for behavioral disclosure. The description adds useful context about default filtering (active groups), pagination, and return fields (name, description, manager, type, sys_id), going beyond simple parameter listings.
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 purpose statement, a compact args list, and a returns section. Every line adds value without unnecessary verbosity.
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 listing tool with four parameters and no output schema, the description covers the essential aspects: what it lists, the default filter, pagination, output format, and return fields. It does not mention limitations or edge cases, but given the simplicity and strong annotations, this is sufficient.
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 valuable examples for the query parameter (e.g., 'active=true', 'nameLIKEnetwork') and summarizes limit/offset and response_format, providing semantic meaning beyond the schema's basic field 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 'List ServiceNow user groups' with a specific verb and resource, distinguishing it from sibling tools like list_incidents or list_users. It immediately conveys the tool's function without ambiguity.
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 (listing groups) and includes example query filters, but it does not explicitly mention alternatives or exclusions. The purpose is unambiguous, so the lack of explicit alternative references is acceptable.
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 readOnly, idempotent, non-destructive. The description adds useful behavior: default query is operational CIs, it returns records with specific fields, and it documents pagination. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with an 'Args' section, common class names, and return info. It's longer than minimal, but every section adds value (examples, defaults, output details). The main summary is front-loaded and the extra details are logically ordered.
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?
With 6 parameters and no output schema, the description fully compensates: it explains every param, provides practical examples, lists common values, and states return content. For a search tool of this complexity, it is essentially 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 baseline is 3. The description enhances semantics by giving concrete encoded query examples (e.g., 'nameLIKEweb-server'), listing common class names, and clarifying response_format options. This adds real meaning beyond raw 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 opens with 'Search for ServiceNow CMDB configuration items (CIs) by name, type, location, or any filter', clearly stating the verb (search), resource (CIs), and scope. This distinguishes it from siblings like servicenow_get_ci (retrieving a specific CI) and generic query 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 gives clear search context: it supports name/type/location filters and lists common class names, implying it's for filtering searches. However, it doesn't explicitly mention alternatives or exclusion scenarios, only implicitly differentiating via the search posture.
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 a non-read, non-destructive mutation. The description adds value by detailing the state machine, the requirement for close_code when closing, and the freedom of emergency transitions. It also discloses that additional_fields can be used for arbitrary updates, which matches the openWorldHint. 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?
The description is well-structured: a one-sentence purpose, a compact state transition list, a summary of key arguments, and a returns line. Every section earns its place, with no filler or repetition. The formatting makes it 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?
Given the tool's complexity (14 parameters, no output schema), the description covers the most nuanced aspects: state transitions and closing requirements. The schema handles individual parameter semantics, while the description provides the workflow context. It does not explain every parameter, but the schema does, and the description addresses the non-obvious behaviors.
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 enhances this by explaining the state transition flow, the meaning of close_code in closing, and the role of additional_fields. It also repeats key parameters like identifier and state, providing quick reference. This goes beyond the schema's individual field 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 action ('Update a ServiceNow change request') and specifies the scope ('state, plan fields, or assignment'). This distinguishes it from generic update tools like servicenow_update_record and from update_incident, while aligning with the dedicated change 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 state transition diagram provides explicit guidance on allowed state sequences and notes that emergency changes can move more freely. It does not explicitly name alternatives, but the tool name and sibling list make it clear this is for change requests. The 'close_code required when closing' note also gives important conditional usage.
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 signal a write operation (readOnlyHint=false) and non-destructive intent (destructiveHint=false), so the bar is lower. The description adds valuable context: content encoding rules (text vs base64), MIME type examples, default encryption behavior, and the return value (created attachment record with sys_id and download link). It does not contradict annotations and goes beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line purpose, an Args list, Returns, and Examples. Each section is compact and information-dense, with no filler. The examples are concise and illustrate two common use cases. It earns every sentence.
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 file-upload tool with several parameters and no output schema, the description covers key aspects: return value, examples, and encoding guidelines. However, it omits the response_format parameter entirely and doesn't mention any limitations (e.g., file size, permission requirements). These gaps leave the agent slightly under-informed for complex scenarios.
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%, giving a baseline of 3. The description goes beyond by explaining content encoding (text as-is, binary base64), providing MIME type examples, and clarifying table_sys_id as sys_id. It also shows practical parameter combinations in examples, which adds meaning beyond the schema alone.
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+object: 'Upload a file as an attachment to a ServiceNow record.' This clearly distinguishes it from sibling tools like list_attachments and get_attachment_content, which are read-only operations. The scope is 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 provides clear usage context through concrete examples (e.g., attaching a log file to an incident, attaching JSON config) that imply when to use this tool. However, it does not explicitly state when not to use it or name alternative tools for similar tasks, so it misses exclusions but covers context well.
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 indicate a non-read-only, non-idempotent write operation, and the description confirms this by describing adding notes/comments. It adds behavioral context by explaining the visibility difference (internal vs customer-visible) and the return value ('Confirmation with updated record'). This goes beyond the annotations but does not disclose additional side effects or authentication requirements, which are not expected given 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 well-structured: a concise purpose statement, an 'Args' section, a return note, and two illustrative examples. Every element adds value, and the information is front-loaded. The examples are not redundant but demonstrate typical usage patterns, making the tool easy to understand 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 that there is no output schema, the description provides a sufficient overview of the tool's behavior, parameters, and return value. It could be more complete by mentioning potential errors or prerequisites (e.g., table must exist and support journal fields), but the information provided is adequate for an agent to correctly invoke the tool in common scenarios. The examples cover both primary use cases (work note and comment).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty, but the description provides detailed parameter semantics for table, identifier, work_note, and comment, including types, constraints, and examples. It clearly explains the difference between work_note and comment and states the requirement that at least one must be provided. This fully compensates for the schema's lack of parameters.
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 'Add' and the resource 'work note or comment to any ServiceNow record that supports journal fields'. It distinguishes between internal work notes and customer-visible comments, which differentiates it from sibling tools like update_record or create_record. The examples further reinforce the specific use case.
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 (adding journal entries to ServiceNow records) and gives practical examples. It does not explicitly mention alternatives or exclusions, but the specification that it applies to records with journal fields and the nature of the operation implicitly distinguishes it from update/delete tools. The constraint that at least one of work_note or comment must be provided is also helpful usage 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by stating that text files return the actual file content while binary files return only metadata and a download URL, which is a significant nuance for agent expectations. It does not contradict annotations and adds useful detail beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise and well-organized into Args, Returns, and Note sections. Every sentence provides necessary information, with no filler or redundancy. The main purpose is front-loaded in the first line, and the note about list_attachments is directly actionable.
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 two-parameter retrieval tool, the description covers the essential context: how to obtain the sys_id, what output to expect for text vs. binary files, and the available response_format options. Combined with the annotations (read-only, idempotent, non-destructive) and the full schema, there are no major gaps in what an agent needs to 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?
Schema description coverage is 100%, both parameters are well-described in the schema. The description adds a crucial semantic detail for sys_id by specifying that it comes from servicenow_list_attachments, which is not in the schema. It also restates response_format's role, though at a higher level than the schema's enum description. This extra provenance guidance elevates the score above the baseline of 3.
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 'Download the content of a file attachment by its sys_id', which clearly identifies the action (download), the resource (file attachment content), and the input (sys_id). It distinguishes itself from siblings like servicenow_list_attachments (which lists metadata) and servicenow_upload_attachment (which uploads), so the purpose is 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 provides a clear prerequisite: 'Use servicenow_list_attachments first to find the sys_id of the attachment.' It also explains behavior for binary vs. text files, which is an implicit when/why to use caution. However, it does not explicitly enumerate alternative tools for downloading binary files or state when this tool should not be used, so it falls just short of a full 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds behavioral context beyond annotations by specifying the return fields (name, scope, version, vendor, status) and providing example usage. 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 well-structured with clearly labeled sections (Intro, Args, Returns, Examples). Every sentence contributes meaningful information: the purpose, parameter usage, return fields, and practical examples. It is appropriately sized and front-loaded with the primary action.
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 tool with 6 parameters, no output schema, and no nested objects, the description is comprehensive. It explains the return fields, provides examples for key use cases, and clarifies parameter behavior. The absence of an output schema makes the 'Returns' line essential, and it is included. Overall, the description gives a complete picture of the tool's functionality.
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 a baseline of 3 is appropriate. The description adds value over the schema by presenting parameters in a practical way, such as grouping limit/offset as 'Pagination' and showing concrete search examples like 'search="ITSM"'. However, it does not fully elaborate on all parameter nuances beyond what the schema already provides, hence a 4 rather than a 5.
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+resource construction: 'List installed ServiceNow scoped applications and active plugins.' This clearly distinguishes it from sibling list tools like servicenow_list_incidents or servicenow_list_users. The title reinforces the scope ('Scoped Applications & 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 clear context for when to use the tool through examples (e.g., 'List all custom applications', 'Find ITSM-related apps', 'Check installed integrations'). While it doesn't explicitly mention exclusions or alternatives (such as 'use list_incidents for incidents'), the purpose is self-explanatory and the examples make the intended use cases evident.
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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only operation. The description adds useful behavioral context by specifying that it returns attachment metadata including filename, content type, size, and download link, and that a blank table_sys_id queries across all attachments. 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 well-structured with Args, Returns, and Examples sections. Each sentence provides necessary information without fluff. It is front-loaded with the main purpose, making it easy to scan and understand quickly.
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 rich annotations and 100% schema coverage, the description still manages to add essential context: it describes the return format (metadata with download link) and gives concrete examples for typical use cases. No critical information is missing for an AI agent to correctly select and invoke this tool.
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?
Input schema has 100% coverage for all 6 parameters, so baseline is 3. The description adds value with practical examples (e.g., INC0001234, .pdf filter) and clarifies that leaving table_sys_id empty lists all attachments for the table. This goes beyond the schema's basic descriptions, earning 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's function: 'List file attachments for a ServiceNow record or query across all attachments.' It uses a specific verb (list) and resource (file attachments), and the scope (by record or across all attachments) distinguishes it from related tools like get_attachment_content 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?
The description provides clear usage examples ('List attachments on INC0001234', 'Find all PDFs on change requests') that illustrate typical scenarios. However, it does not explicitly mention when not to use this tool (e.g., if downloading content, use get_attachment_content), so it lacks explicit exclusions or alternative tool references.
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 readOnly/openWorld/idempotent, and the description adds default behavior ('all active items'), filter semantics (partial match), and return fields. No contradiction. It doesn't discuss pagination details or error cases, but with strong annotations 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 compact and front-loaded with a one-sentence purpose, followed by short Args/Returns/Examples sections. No filler; every clause adds value, and examples are illustrative. Minor redundancy with schema defaults doesn't hurt.
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 adequately explains what is returned (name, description, category, price) and how to constrain results. It covers query, category, pagination, and format. Missing edge cases are minor given the tool's simplicity.
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 parameters with concrete query syntax like 'nameLIKElaptop' and category partial-match behavior. It also clarifies response_format choices and pagination parameters. This goes beyond the schema's own 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 one-line description 'Browse available service catalog items' uses a clear verb and resource, and the title mirrors it. It differentiates from sibling tools like get_catalog_item (singular detail) and submit_catalog_request by scoping to browsing/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?
The description provides practical usage context: 'Browse hardware items → category="Hardware"' and query filter examples. It implies use for exploratory lookups of catalog items, though it doesn't explicitly mention alternatives/exclusions. It gives enough context to choose this tool over generic list or 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?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is known. The description adds valuable context by explaining request states, default query behavior, and return fields, going 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 well-organized with a clear purpose statement, parameter breakdown, state reference, and return specification. Every sentence conveys useful 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 read-only list tool with strong annotations and simple parameters, the description is complete. It states what records are returned and the meaning of state values, leaving no significant gaps.
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 parameters by providing a concrete query example ('opened_by=javascript:gs.getUserID()') and mapping state numbers to meanings, which is not present in 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 it lists service catalog requests (REQ records) with filters, using a specific verb and resource. This distinguishes it from sibling tools like list_incidents or list_changes.
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 explains the default behavior (open requests) and provides example query syntax, giving clear context for use. It does not explicitly name alternatives or exclusions, but the tool's scope is self-evident from its name and description.
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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about the expected return value ('List of matching records with pagination metadata') and query encoding, which goes beyond the annotations. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: a one-line purpose, a usage note, an Args block, a Returns line, and examples. It is appropriately sized for a 7-parameter tool, though the Args block largely repeats the schema JSON. Still, the examples and usage guidance earn their place, and the structure is front-loaded with the core purpose.
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 generic query tool with many parameters and no output schema, the description covers the essential aspects: purpose, when to use, parameter semantics, return value, and examples. It does not discuss error handling (e.g., invalid table names) or edge cases, but these are less critical given the open-world annotation and the tool's flexible nature.
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%, so the schema already documents all parameters. The description goes further by providing concrete examples of query strings (e.g., 'state=1^priority=1', 'assigned_to=CURRENT_USER') and clarifying subtle behaviors like display_value='all' returning both display and raw values. This adds contextual meaning beyond the schema's field 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 states 'Query records from any ServiceNow table using an encoded query string', clearly identifying the tool as a generic query operation. It differentiates from siblings by noting it is for 'ad-hoc queries on any table not covered by specialized tools', which is explicit and actionable.
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 explicitly says 'Use this for ad-hoc queries on any table not covered by specialized tools', giving clear guidance on when to use it. The existence of many specialized sibling tools (e.g., servicenow_list_incidents, servicenow_list_changes) makes this exclusion meaningful, and the examples illustrate appropriate 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?
Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral detail: the dry-run default, the safety cap via 'limit', and the return behavior ('Preview list (dry_run=true) or per-record success/failure results'). This goes beyond annotations by explaining the commit process and safeguards, which is essential for a bulk mutation tool.
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-organized with a one-sentence summary, an Args list, Returns, and Examples. It is front-loaded with the key safety warning. However, the Args list largely duplicates schema descriptions, though the examples add 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?
The description covers the tool's purpose, key parameters, safety features, and output behavior. It includes three practical examples that illustrate common use cases. Since there is no output schema, the Returns line is essential and provided. This is comprehensive for a bulk update tool.
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 describes all six parameters with 100% coverage. The description repeats them but adds context: 'limit' is described as a 'Safety cap — max records to process' rather than just a maximum results count, and examples show realistic encoded queries for 'query' and usage patterns for 'data'. The Returns line clarifies what different parameter values produce.
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 and resource: 'Update multiple records matching a query.' This clearly distinguishes it from sibling tools like servicenow_update_record (single record) and servicenow_bulk_delete (delete). The title 'Bulk Update Records' reinforces the 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?
It clearly states the tool is for updating multiple records matching a query, implying bulk operations. It provides safety guidance: 'Dry-run by default — always preview before committing.' However, it doesn't explicitly name alternatives like servicenow_update_record for single-record updates, so exclusions are 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.
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 context: 'Deletion is permanent', the default dry-run behavior, and the safety cap (limit max 20/100). It warns about irreversible consequences and explains the preview-first workflow, going well beyond the annotation.
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 an Args list and examples, but it's longer than necessary since the Args section largely duplicates the input schema. The warning and examples are valuable, so the extra length is justified, yet could be trimmed.
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 behavior: what it deletes, how to preview, safety limits, and output format options via response_format. Since the input schema is thorough and the tool is relatively simple, the description is sufficiently complete, though return value details are absent.
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 covers 100% of parameters with descriptions, but the tool description adds value by clarifying that 'limit' is a 'Safety cap — max records to delete' (while the schema misleadingly says 'Maximum number of results to return'), and explains the dry_run default behavior in context. It also provides encoded query examples that demonstrate syntax.
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 'Delete multiple records matching a query', a specific verb and resource that distinguishes it from sibling tools like servicenow_delete_record (single delete) and servicenow_bulk_update. The bulk scope is explicit.
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: 'Dry-run by default — always preview before committing' and 'Always run with dry_run=true first to confirm scope.' It advises a safe workflow and includes concrete examples with table/query patterns, making it clear when and how to use this tool.
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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds valuable behavioral context: default query of active users only, pagination via limit/offset, response_format choices, and the specific return fields (name, username, email, department, manager). This goes beyond the annotations with 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?
The description is well-organized and concise: a one-sentence purpose, followed by a clear Args section and a Common queries section with examples, then a Returns line. Every element serves a purpose, and the structure makes it easy to scan.
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 has 4 parameters with full schema documentation and no output schema, the description provides a complete picture: purpose, input parameters, query examples, pagination, output format, and return fields. It supplies sufficient context for an agent to select and invoke the tool correctly without missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 significantly adds meaning by explaining the query parameter with concrete examples ('nameLIKEjohn', 'department.name=Information Technology') and listing common queries, plus clarifying limit/offset as pagination and response_format as output format. This is far more helpful than the schema alone.
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 'List and search ServiceNow users', which is a specific verb and resource. This distinguishes it from siblings like servicenow_get_user (which fetches a single user) and servicenow_query_records (generic query). The name and title reinforce the plural list/search 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 for use by giving common query examples (active users, name search, department, role) and noting default behavior. However, it does not explicitly mention when to use an alternative tool (e.g., for a single user, use get_user) or provide when-not-to-use guidance, 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.

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:

[![servicenow-mcp-server MCP server](https://glama.ai/mcp/servers/kylburns89/servicenow-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/kylburns89/servicenow-mcp-server)

Score Badge

Copy to your README.md:

[![servicenow-mcp-server MCP server](https://glama.ai/mcp/servers/kylburns89/servicenow-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/kylburns89/servicenow-mcp-server)

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/kylburns89/servicenow-mcp-server'

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