This project is meant as a helper tool for service now developer. It provides a simple, desktop native UI to make Rest API call to a ServiceNow instance and to browse and query the result.
From standard Table API operations, such as selecting filtered records in a table, you will be able to perform advanced operations, like join operations between tables and grouping.
The same APIs used for the user interface also powers a local MCP server, so your AI model of choice can browse and study your ServiceNow instance.
This tool provides read-only methods, although PUT calls may be added in the future.
This project is an independent, community tool: it is not affiliated with or endorsed by ServiceNow. ServiceNow is a trademark of ServiceNow, Inc.
This tool pulls data from a selected ServiceNow instance, using user provided authentication, to process it locally. Always make sure not to violate your organization's policies. I do not in any way condone misuse of this tool. To report a vulnerability, or to see what the tool stores and how, read the security policy.
To get started with this tool first configure your instance and authentication methods in the Configuration tab. Note: Your credentials are only saved locally and sent to ServiceNow to authenticate your requests.
Configuration: settings, instances and authentication methods.
User interface: tabs and sidebar.
Database: what is stored locally and where, how responses are reused and when they expire.
MCP: the MCP server and its tools.
Each release includes two setup executables, for Windows and for Linux .
Simply download the setup for your system and run it to install the application (portable ~180MB, but you can build the project yourself to save storage).
The installers are not code-signed, so Windows SmartScreen may warn you the first time you run the setup. See Building and installing for what to expect, how to verify the download and how to build it yourself.
This project is written entirely in Python.
I used Pyside6 for the UI and the mcp package for the MCP server.
The list of packages needed to build this application is in the requirement.txt file.
build_linux.sh and build_windows.sh build the application and its installer with a
single command. See Building and installing.
Add tables to a response cached by request_tables, so query_cache can join them with the tables it already holds. Only the new tables are fetched. If the cached response has expired, every table is requested again into a new cached response and the returned cache_name changes. Returns the same summary as request_tables, for every table of the response.
| Name | Required | Description | Default |
|---|---|---|---|
| tables | Yes | The tables to add, each with its own query, fields and limit. A table already in the cached response cannot be added again. | |
| cache_name | Yes | The cache_name returned by request_tables or add_tables, or listed by list_cached_responses with request_type multiple_tables. |
| Name | Required | Description |
|---|---|---|
| source | Yes | |
| sections | Yes | |
| warnings | Yes | |
| row_count | Yes | |
| cache_name | Yes | |
| elapsed_ms | Yes | |
| executed_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only and open-world annotations, it discloses incremental fetching and the non-obvious expiry path: every table is refetched, a new cached response is created, and the returned cache_name changes. It also clarifies that the returned summary covers every table, not only the additions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences progress from purpose to fetch behavior, expiration behavior, and result scope. Every sentence provides operationally useful information without filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The rich input schema and output schema cover argument and return details, while the description supplies the workflow and cache-lifecycle context needed for correct invocation. The expiration warning and changed cache_name address especially important non-obvious behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already documents both arguments and their query options. The description adds useful lifecycle semantics for cache_name and clarifies that the supplied tables are incremental additions, including how expiration affects the cache identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence specifies the operation and resource: extending a response cached by request_tables with additional tables for query_cache joins. Naming both sibling tools distinguishes this from creating a cached response and querying one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It establishes the prerequisite of an existing request_tables cache and explains the intended downstream use with query_cache. It does not explicitly state when not to use it or direct agents to request_tables when starting a fresh cached response.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the fields of a table from the instance dictionary, including the fields it inherits from the tables it extends, for example task for incident. Each field has its name, label and type, the table that defines it, the table it points to for reference and list fields, and whether it is mandatory or read only. The dictionary overrides of the table and of its parents are applied and listed under overrides. default_value, dependent and choices appear only when the field has them; choices are the active values and labels to use in queries, with the dependent_value of the dependent field when they depend on one. Use it before querying a table whose fields you do not know for sure, custom application tables included. Inactive fields are left out. The returned cache_name holds the tables sys_db_object, sys_dictionary, sys_dictionary_override and sys_choice, where name is the table and element the field.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | ServiceNow table name, for example incident or sys_user. | |
| fields | No | Only describe these fields, for example ["state", "caller_id"]. Empty describes every field of the table. | |
| refresh | No | Skip the local cache and ask the instance again. Leave false to reuse a recent response. | |
| instance | Yes | Name of a configured instance, as returned by list_instances. |
| Name | Required | Description |
|---|---|---|
| label | Yes | |
| table | Yes | |
| fields | Yes | |
| source | Yes | |
| extends | Yes | |
| warnings | Yes | |
| cache_name | Yes | |
| executed_at | Yes | |
| field_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/openWorld, so the description's real contribution is behavioral: inactive fields are omitted, dictionary overrides from parents are applied and listed, and default_value/dependent/choices appear only conditionally. It also discloses that the response carries a cache_name pointing at sys_db_object, sys_dictionary, sys_dictionary_override and sys_choice, which is useful context beyond the annotations, though permissions and failure modes are not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first clause, and every sentence carries substantive content about return shape or usage. It is dense and somewhat run-on in the middle ('the table that defines it, the table it points to for reference and list fields'), which slightly hurts scanability but not clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex describe tool with an output schema, the description covers what is returned, what is conditionally returned, what is filtered out, and how caching interacts with the result. Remaining gaps, such as the effect of the 'fields' filter on the returned structure, are adequately covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds no additional meaning for the 'fields', 'refresh', or 'instance' arguments, so it sits at the baseline for a fully described schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('List the fields of a table from the instance dictionary') and immediately scopes it by naming inheritance and the concrete example 'task for incident'. That is enough to distinguish it from data-fetching siblings like request_table or request_tables without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear trigger: 'Use it before querying a table whose fields you do not know for sure, custom application tables included.' It does not name an alternative tool or state when not to use it, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a cached response to disk, as csv with one file per table or as an xlsx workbook with one sheet per table. Returns the absolute paths written.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | csv writes one file per table, xlsx one workbook with a sheet per table. | csv |
| cache_name | Yes | The cache_name returned by a request tool or by list_cached_responses. | |
| destination | No | Directory to write into. Empty uses the exports folder inside the panel data directory. |
| Name | Required | Description |
|---|---|---|
| paths | Yes | |
| format | Yes | |
| tables | Yes | |
| cache_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=false, so safety and repeatability are covered. The description adds the on-disk side effect and the file-layout semantics (one file/sheet per table), but says nothing about overwriting existing files, permissions on the destination, or failure behavior when the directory is unwritable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two front-loaded sentences with no filler; the format choice is stated first and the destination behavior last. The trailing 'Returns the absolute paths written' is somewhat redundant given an output schema exists, keeping it just short of a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage, rich annotations, and an output schema for return values, the description only needs to carry the write semantics, which it does. The remaining gap is operational behavior (overwrite policy, destination write errors) for a tool that writes files to disk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description restates the csv/xlsx table layout that the format enum already documents and says nothing about destination or the cache_name handle, adding no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb and resource (write a cached response to disk) plus the two output shapes, so an agent can tell this apart from read-side siblings like query_cache and list_cached_responses. It stops short of naming a sibling or stating the contrast explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the cache_name parameter's schema note points at 'a request tool or list_cached_responses' as the source of the handle, but the description itself gives no when-to-use, prerequisites, or when-not guidance versus query_cache.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the responses in the local cache, most recent first, with the tables and row counts each holds. current is false once a response is older than the cache lifetime: it can still be queried and exported, but request tools will fetch fresh data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of cached responses to list, most recent first. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real behavioral context beyond that — result ordering, that each entry includes its tables and row counts, and the staleness model (entries older than the cache lifetime keep their data but trigger fresh fetches by request tools). It does not mention pagination limits or whether listing itself refreshes anything, which keeps it off a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the core action and ordering front-loaded and the staleness caveat after it. The phrase "current is false" appears without an antecedent in the description, a minor ambiguity that costs it a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description needn't document return fields, and it correctly spends its words on ordering, entry contents, and the stale-entry lifecycle instead. For a one-parameter read tool with annotations, that is nearly complete; only pagination behavior and explicit sibling routing are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a single self-documented `limit` parameter (default 20, max 200), so the schema carries the load and the baseline is 3. The description reinforces ordering ('most recent first') but adds no new meaning about how limit interacts with the cache contents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"List the responses in the local cache, most recent first, with the tables and row counts each holds" gives a specific verb, resource, ordering, and return content, which separates it from query_cache and export_cache named later in the text. It stops short of explicitly stating the sibling contrast (e.g., 'use list_cached_responses to discover what is available before calling query_cache'), so it is clear but not maximally differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the agent can infer this is a discovery/inventory call, and the note that stale entries 'can still be queried and exported, but request tools will fetch fresh data' hints at follow-up routing. There is no explicit when-to-use/when-not or a named alternative such as query_cache or request_table.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the configured ServiceNow instances and whether each has a usable MCP authentication method. The other tools take the instance name returned here.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds genuinely useful behavior beyond that: results include per-instance auth usability, and the returned names are the identifiers other tools accept. It does not mention pagination, ordering, or failure behavior, but with zero params and an output schema those are minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no waste. The core purpose is front-loaded and the downstream-consumption note follows, which is the right ordering for an agent scanning definitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter discovery tool with an output schema present, the description covers purpose, the extra auth-validity signal, and the role of its output in subsequent calls. Nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there is nothing for the description to disambiguate; baseline for a 0-param tool applies. The sentence about other tools consuming the returned instance name is useful context, though it describes output rather than input semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource: "List the configured ServiceNow instances," plus a second dimension of what is returned (whether each has a usable MCP auth method). It also ties itself to the sibling set by stating that the other tools consume the instance name returned here, so an agent can place it immediately in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case clear: call this to discover instance names that the other tools require, which is effectively a prerequisite/bootstrapping instruction. It does not state any when-not-to-use condition or what to do if no instance reports a usable auth method, leaving a small gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run read-only SQLite against a cached response. Each ServiceNow table is a SQLite table with TEXT columns. Returns at most 2000 rows; truncated is true when more matched.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQLite statements, separated by semicolons. Every cached ServiceNow table is a SQLite table with the same name and TEXT columns. Reference fields hold the sys_id of the referenced record: join on it, or request dot-walked fields such as group.name. Double-quote column names that contain dots or are SQL keywords, for example "caller_id.name", "group", "order" and "when". Only the last statement that returns rows is returned. The cache is read-only, TEMP tables are allowed. | |
| cache_name | Yes | The cache_name returned by a request tool or by list_cached_responses. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| columns | Yes | |
| row_count | Yes | |
| truncated | Yes | |
| cache_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint=false, but the description adds real operational context beyond them: a hard 2000-row cap and the truncated flag that signals when more rows matched. That truncation behavior is the single most important thing an agent needs to interpret results correctly, and it is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and immediately followed by the data model the agent must reason about. Every sentence earns its place and nothing is padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-shape explanation is unnecessary, and the description covers the one result-side surprise (truncation). It is nearly complete for a two-parameter query tool; the only missing piece is guidance on cache lifecycle relative to the request tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema's sql description is itself detailed about semicolon separation, dot-walking, quoting, and the last-returned-statement rule. The tool description only restates that tables are SQLite with TEXT columns, adding no syntax or edge-case meaning not already in the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Run read-only SQLite against a cached response,' which tells an agent exactly what the tool does. It does not, however, contrast itself with siblings like describe_table, request_table, or export_cache, so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent must already hold a cache_name to have any reason to call this. There is no explicit when-to-use versus describe_table or export_cache, and no stated prerequisite that a cache must first be populated by a request tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch records from one ServiceNow table. Returns a sample of the records, any warnings and a cache_name; the full result is cached locally for query_cache and export_cache. To join several tables, fetch them with request_tables instead.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to fetch, 100 when omitted. When exactly this many records come back, limit_reached is true and more records probably match: ask again with a higher limit. Above 10000 the request is split into several calls. | |
| query | No | Encoded query passed as sysparm_query, for example active=true^priority=1. Empty returns every record up to the limit. ServiceNow ignores conditions on fields the table does not have and returns the records unfiltered, so use the exact field names, as listed by describe_table: for example business rules in sys_script name their table in collection, not table. | |
| table | Yes | ServiceNow table name, for example incident or sys_user. | |
| fields | No | Field names passed as sysparm_fields. Dot-walking is allowed, for example caller_id.name. Empty returns every field. | |
| refresh | No | Skip the local cache and ask the instance again. Leave false to reuse a recent response. | |
| instance | Yes | Name of a configured instance, as returned by list_instances. | |
| order_by | No | Field name passed as sysparm_order_by. Empty keeps the instance order. | |
| max_records | No | How many of the fetched records to return in this response. The full result stays in the local cache: use query_cache with the returned cache_name to read the rest. |
| Name | Required | Description |
|---|---|---|
| limit | Yes | |
| table | Yes | |
| source | Yes | |
| columns | Yes | |
| records | Yes | |
| warnings | Yes | |
| row_count | Yes | |
| cache_name | Yes | |
| elapsed_ms | Yes | |
| executed_at | Yes | |
| limit_reached | Yes | |
| sample_truncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, open-world and idempotent, so the safety profile is covered. The description adds genuinely non-obvious behavior: only a sample plus warnings and a cache_name come back, while the full result is cached locally for query_cache/export_cache — that is real information not present in the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, return shape stated before the alternative-tool routing. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given eight parameters, an output schema and rich annotations, the description covers the essentials: scope, return payload, caching follow-up, and the sibling alternative. Error/permission behavior is left implicit, a minor gap for an open-world read against a remote instance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline would be 3, but the description supplies cross-parameter semantics the schema does not: the returned cache_name is the handle for reading the remainder via query_cache, which ties max_records to the caching tools. It does not restate per-field syntax, which is correctly left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource ('Fetch records from one ServiceNow table') with explicit single-table scope, and it names the sibling it is not (request_tables) in the same breath. An agent can distinguish this from request_tables without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes multi-table/join cases to request_tables and points at query_cache/export_cache for the full result set, giving a clear selection rule. It stops short of stating when to prefer refresh=true versus the cache, leaving that judgement to the per-parameter text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch several tables in one request, each with its own query, fields and limit. All of them are stored in one cached response, so query_cache can join them. Returns the row count and columns of each table, any warnings and the cache_name. Example arguments: {"instance": "dev", "tables": [{"table": "sys_user_group", "fields": ["sys_id", "name"], "limit": 1000}, {"table": "sys_group_has_role", "query": "role.name=itil", "fields": ["group", "role", "group.name"], "limit": 5000}]}
| Name | Required | Description | Default |
|---|---|---|---|
| tables | Yes | The tables to fetch, each with its own query, fields and limit. Each table can appear only once: combine conditions with ^OR or IN instead. | |
| refresh | No | Skip the local cache and ask the instance again. Leave false to reuse a recent response. | |
| instance | Yes | Name of a configured instance, as returned by list_instances. |
| Name | Required | Description |
|---|---|---|
| source | Yes | |
| sections | Yes | |
| warnings | Yes | |
| row_count | Yes | |
| cache_name | Yes | |
| elapsed_ms | Yes | |
| executed_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and open-world. The description adds meaningful behavior beyond those annotations: all tables are stored in one cached response, query_cache can join them, and the result includes row counts, columns, warnings, and cache_name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded, efficient, and free of wasted wording. The example is directly useful for illustrating the nested table request structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema, annotations, and output schema, the description is complete enough for correct invocation. It covers the multi-table caching behavior, the query_cache relationship, and the returned summary, and supplies an example of the argument shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents instance, refresh, and each table's query, fields, and limit. The description reinforces that each table has its own query/fields/limit and provides an example, but it does not add semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: fetch several tables in one request, each with its own query, fields, and limit. The phrase 'several tables' clearly distinguishes it from the singular sibling request_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context for fetching multiple tables and notes that query_cache can join the cached response. It does not explicitly name request_table or add_tables as alternatives, but the multi-table scope implies the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether users holding the given sets of roles can run an operation on a table, or on one of its fields, according to the ACLs of the instance. Each profile gets a decision (allowed, conditional, denied or missing), a summary, the reasons and the controls involved. Scripts and conditions are not run: conditional means the scripts and conditions listed in the controls decide. The controls also show which roles each ACL requires. Parent table inheritance is not evaluated: missing means no ACL matched.
| Name | Required | Description | Default |
|---|---|---|---|
| field | No | Optional field name, to verify field level controls. Only for the read and update operations. | |
| table | Yes | ServiceNow table name, for example incident or sys_user. | |
| refresh | No | Skip the local cache and ask the instance again. Leave false to reuse a recent response. | |
| instance | Yes | Name of a configured instance, as returned by list_instances. | |
| profiles | Yes | One list of role names per user to check, for example [["itil", "snc_internal"], ["admin"]]. List every role the user holds, including snc_internal and the roles contained in other roles: none is added automatically. A user passes a control when any of its roles is required by the control. Empty lists are ignored. Roles are compared locally and never sent to the instance. | |
| operation | Yes | The operation to verify. |
| Name | Required | Description |
|---|---|---|
| field | Yes | |
| table | Yes | |
| source | Yes | |
| target | Yes | |
| profiles | Yes | |
| acl_names | Yes | |
| operation | Yes | |
| cache_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly/openWorld/idempotent; the description goes well beyond them by disclosing that scripts and conditions are never run, that 'conditional' means the listed controls decide, that 'missing' means no ACL matched rather than an inherited denial, and that the controls reveal which roles each ACL requires. These are exactly the interpretation caveats an agent needs to avoid misreading the result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences: purpose first, then output shape, then the two interpretive caveats. No repetition of the tool name, no filler, and each sentence carries information an agent would otherwise have to guess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter, read-only verification tool with an output schema, the description covers the remaining interpretive burden: what each decision value means and the two evaluation boundaries (no script execution, no parent inheritance). Nothing needed to call it or interpret it correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains profiles nesting, the field's read/update restriction, refresh caching, and instance sourcing. The description adds no parameter-level detail beyond the schema; its added meaning is about outcome semantics (allowed/conditional/denied/missing), not the inputs. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Check whether users holding the given sets of roles can run an operation on a table, or on one of its fields, according to the ACLs of the instance.' No sibling tool (list_instances, describe_table, request_table, query_cache...) performs ACL evaluation, so the scope is unambiguous even without naming an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear what question the tool answers and flags two important scoping limits that determine whether its answer applies: scripts and conditions are not executed, and parent table inheritance is not evaluated. It stops short of explicitly naming sibling tools or stating when to prefer them, so it is strong context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_tablesdescribe_tableexport_cachelist_cached_responseslist_instancesquery_cacherequest_tablerequest_tablesverify_aclScored across 9 tools
Each tool targets a distinct operation: instance discovery, schema inspection, single vs. multi-table fetching, cache querying/exporting, ACL verification, and cache listing. The single/plural fetch pair and add_tables are clearly differentiated by their descriptions and explicit guidance.
All tool names follow a consistent snake_case verb_noun convention (list_instances, describe_table, request_table, query_cache, export_cache, verify_acl, list_cached_responses). No mixed casing or vague verb-only names.
Nine tools is well-scoped for a ServiceNow data exploration and ACL verification server. Each tool has a clear role in the workflow, with no redundant or filler tools.
The surface covers instance discovery, schema inspection, record fetching, SQL querying, export, ACL checks, and cache management. It appears intentionally read-only, so record mutation and explicit cache invalidation are minor gaps rather than dead ends.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
One governed MCP endpoint for 40+ business systems. Read-only, source-cited answers.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
