Skip to main content
Glama

sn_attach

List, download, or upload attachments on ServiceNow records with inline base64 data, enabling attachment management without host filesystem access.

Instructions

Manage attachments on ServiceNow records. List, download, or upload attachments. Bytes are exchanged inline as base64; this tool never reads or writes the host filesystem, so it behaves identically for local, containerized, and remote servers.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>",
      "profile": "<profile>"
    },
    "name": "sn_attach"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum attachments to list (default 100, max 1000)
tableNoOwning table name (required for list, download, and upload)
actionYesAttachment operation: list, download, or upload
offsetNoDeterministic list offset (default 0)
sys_idNoOwning 32-hex record sys_id (required for list, download, and upload)
profileYesConfigured ServiceNow profile name (required; no default fallback).
file_nameNoLeaf filename without path separators (required for upload)
content_typeNoMIME type for upload, e.g. 'application/pdf' or 'text/plain; charset=utf-8' (default: application/octet-stream)
content_base64NoBase64 attachment bytes (required for upload). Standard base64 alphabet; line breaks are accepted and trailing '=' padding is optional. Decoded bytes must not exceed 10 MiB. The stdio transport frames messages by newline with no size limit, so that 10 MiB is the only ceiling in force.
attachment_sys_idNo32-hex attachment sys_id (required for download)

Output Schema

NameRequiredDescriptionDefault
dataYes
profileYesConfigured ServiceNow profile name (required; no default fallback).
metadataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.3.0
    • addedOutput schema / properties / metadata / properties / cache
      Added value: +{
      +  "enum": [
      +    "hit",
      +    "miss",
      +    "bypass",
      +    "mixed"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / metadata / properties / timing
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "total_ms": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "upstream_ms": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "watermark_ms": {
      +      "minimum": 0,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "total_ms",
      +    "upstream_ms",
      +    "watermark_ms"
      +  ],
      +  "type": "object"
      +}
  2. Changed17 schema fields changedv2.2.0
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / attachment_sys_id / description
      Previous value: -"Attachment sys_id (required for download)"New value: +"32-hex attachment sys_id (required for download)"
    • addedInput schema / properties / attachment_sys_id / pattern
      Added value: +"^[0-9a-f]{32}$"
    • addedInput schema / properties / content_base64
      Added value: +{
      +  "description": "Base64 attachment bytes (required for upload). Standard base64 alphabet; line breaks are accepted and trailing '=' padding is optional. Decoded bytes must not exceed 10 MiB. The stdio transport frames messages by newline with no size limit, so that 10 MiB is the only ceiling in force.",
      +  "maxLength": 14348938,
      +  "type": "string"
      +}
    • changedInput schema / properties / content_type / description
      Previous value: -"MIME type for upload (default: application/octet-stream)"New value: +"MIME type for upload, e.g. 'application/pdf' or 'text/plain; charset=utf-8' (default: application/octet-stream)"
    • addedInput schema / properties / content_type / maxLength
      Added value: +255
    • addedInput schema / properties / file_name
      Added value: +{
      +  "description": "Leaf filename without path separators (required for upload)",
      +  "maxLength": 255,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • removedInput schema / properties / file_path
      Removed value: -{
      -  "description": "Local file path to upload",
      -  "type": "string"
      -}
    • addedInput schema / properties / limit
      Added value: +{
      +  "default": 100,
      +  "description": "Maximum attachments to list (default 100, max 1000)",
      +  "maximum": 1000,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "Deterministic list offset (default 0)",
      +  "maximum": 10000,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • removedInput schema / properties / output_path
      Removed value: -{
      -  "description": "Local file path to save downloaded attachment",
      -  "type": "string"
      -}
    • addedInput schema / properties / profile
      Added value: +{
      +  "description": "Configured ServiceNow profile name (required; no default fallback).",
      +  "maxLength": 128,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedInput schema / properties / sys_id / description
      Previous value: -"Record sys_id (required for list and upload)"New value: +"Owning 32-hex record sys_id (required for list, download, and upload)"
    • addedInput schema / properties / sys_id / pattern
      Added value: +"^[0-9a-f]{32}$"
    • changedInput schema / properties / table / description
      Previous value: -"Table name (required for list and upload)"New value: +"Owning table name (required for list, download, and upload)"
    • changedInput schema / required
      Previous value: -[
      -  "action"
      -]New value: +[
      +  "action",
      +  "profile"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "data": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "action": {
      +          "enum": [
      +            "list",
      +            "download",
      +            "upload"
      +          ],
      +          "type": "string"
      +        },
      +        "result": {
      +          "anyOf": [
      +            {
      +              "type": "null"
      +            },
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "number"
      +            },
      +            {
      +              "type": "boolean"
      +            },
      +            {
      +              "additionalProperties": {},
      +              "propertyNames": {
      +                "type": "string"
      +              },
      +              "type": "object"
      +            },
      +            {
      +              "items": {},
      +              "type": "array"
      +            }
      +          ]
      +        }
      +      },
      +      "required": [
      +        "action",
      +        "result"
      +      ],
      +      "type": "object"
      +    },
      +    "metadata": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "kind": {
      +          "enum": [
      +            "single",
      +            "collection",
      +            "operation"
      +          ],
      +          "type": "string"
      +        },
      +        "limits": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "max_bytes": {
      +              "maximum": 14680064,
      +              "minimum": 1000,
      +              "type": "integer"
      +            },
      +            "max_records": {
      +              "exclusiveMinimum": 0,
      +              "maximum": 9007199254740991,
      +              "type": "integer"
      +            }
      +          },
      +          "required": [
      +            "max_records",
      +            "max_bytes"
      +          ],
      +          "type": "object"
      +        },
      +        "pagination": {
      +          "anyOf": [
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "mode": {
      +                  "const": "none",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "mode"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "has_more": {
      +                  "type": "boolean"
      +                },
      +                "limit": {
      +                  "exclusiveMinimum": 0,
      +                  "maximum": 9007199254740991,
      +                  "type": "integer"
      +                },
      +                "mode": {
      +                  "const": "offset",
      +                  "type": "string"
      +                },
      +                "next_offset": {
      +                  "maximum": 9007199254740991,
      +                  "minimum": 0,
      +                  "type": "integer"
      +                },
      +                "offset": {
      +                  "maximum": 9007199254740991,
      +                  "minimum": 0,
      +                  "type": "integer"
      +                },
      +                "order_by": {
      +                  "items": {
      +                    "minLength": 1,
      +                    "type": "string"
      +                  },
      +                  "maxItems": 8,
      +                  "minItems": 1,
      +                  "type": "array"
      +                },
      +                "recovery": {
      +                  "const": "adjust_request_and_retry_same_offset",
      +                  "type": "string"
      +                },
      +                "returned": {
      +                  "maximum": 9007199254740991,
      +                  "minimum": 0,
      +                  "type": "integer"
      +                }
      +              },
      +              "required": [
      +                "mode",
      +                "limit",
      +                "offset",
      +                "returned",
      +                "has_more",
      +                "order_by"
      +              ],
      +              "type": "object"
      +            }
      +          ]
      +        },
      +        "record_count": {
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "truncation": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "dropped_records": {
      +              "maximum": 9007199254740991,
      +              "minimum": 0,
      +              "type": "integer"
      +            },
      +            "reason": {
      +              "enum": [
      +                "record_limit",
      +                "byte_limit"
      +              ],
      +              "type": "string"
      +            },
      +            "truncated": {
      +              "type": "boolean"
      +            }
      +          },
      +          "required": [
      +            "truncated"
      +          ],
      +          "type": "object"
      +        }
      +      },
      +      "required": [
      +        "kind",
      +        "record_count",
      +        "limits",
      +        "pagination",
      +        "truncation"
      +      ],
      +      "type": "object"
      +    },
      +    "profile": {
      +      "description": "Configured ServiceNow profile name (required; no default fallback).",
      +      "maxLength": 128,
      +      "minLength": 1,
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "data",
      +    "metadata",
      +    "profile"
      +  ],
      +  "type": "object"
      +}
  3. First observedv1.0.0

TDQS

A4/5.0
Behavior4/5

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

The annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds genuinely useful behavior beyond that: bytes move inline as base64 and the host filesystem is never touched, so behavior is identical across local, containerized, and remote deployments. It stops short of disclosing upload side effects (overwrite vs. duplicate on same filename) or ordering/pagination behavior for list.

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

Conciseness5/5

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

Two sentences, zero padding, with the core operation set front-loaded and the filesystem caveat immediately after. Every clause carries information an agent would otherwise have to infer.

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 10-parameter tool with an output schema (so return values need no explanation) and full schema coverage, the description covers the one genuinely non-obvious trait — inline base64 with no filesystem access. It leaves minor gaps around per-action parameter applicability and what an upload returns or replaces.

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 every parameter is already documented in the schema, including the 10 MiB decoded ceiling and the 32-hex patterns. The description only reinforces the inline-base64 transfer model, adding no per-action parameter mapping (which params apply to list vs. download vs. upload) beyond what the schema states.

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

Purpose5/5

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

The description names a specific resource (attachments on ServiceNow records) and enumerates the exact operations the single `action` parameter exposes: list, download, upload. That scopes it cleanly away from the record-oriented siblings like sn_get and sn_query, which operate on record fields rather than binary attachments.

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 three operation modes are stated, so the agent knows what the tool can do, but there is no guidance on when to reach for this versus sn_get/sn_query, nor any prerequisites such as needing a valid profile or which fields are mandatory per action. Usage is implied by the action enum rather than explained.

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