Skip to main content
Glama

upload_attachment

Attach a file to a ServiceNow record from a local path, URL, or Base64 content, returning sha256 and size to verify the upload arrived intact.

Instructions

Attach a file to a ServiceNow record (requires WRITE_ENABLED=true). Provide ONE of: file_path (a file on the machine running NowAIKit, local server only), source_url (the server fetches it), or content_base64 (small files only). file_path and source_url never pass the file through this tool call, so prefer them for anything over ~20KB: a model can only write a limited amount of text in a single call. Returns sha256 and size_bytes of what was sent so you can confirm the attachment is intact.

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": {
      "table": "<table>",
      "record_sys_id": "<record_sys_id>"
    },
    "name": "upload_attachment"
  }
}

Input Schema

NameRequiredDescriptionDefault
tableYesTable name (e.g. "incident", "kb_knowledge")
file_nameNoFile name including extension (e.g. "screenshot.png"). Optional with file_path (defaults to the file's own name).
file_pathNoPath to a file on the machine running NowAIKit (local stdio server: Claude Desktop, Claude Code, Cursor, etc.). Works on Windows, macOS and Linux: absolute paths (C:\Users\me\report.xlsx, /Users/me/report.xlsx), ~/ paths, file:// URLs, or paths relative to the server's working folder. Secrets (SSH/cloud keys, .env files, credential stores, MCP client configs) are always refused. Not available on remote/hosted servers.
source_urlNoPREFERRED. http(s) URL the server fetches the file from and attaches directly. Use this for anything larger than a few hundred KB. Bytes never travel through this tool call.
content_typeNoMIME type (e.g. "image/png", "application/pdf"). Optional when source_url is used (inferred from the response or file extension).
record_sys_idYessys_id of the record to attach the file to
content_base64NoBase64-encoded file content. Only for small files. Use source_url for anything larger.
source_auth_headerNoOptional Authorization header value sent when fetching source_url (e.g. "Bearer <token>" or "Basic <creds>") for any protected URL that requires authentication.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv5.0.1
    • changedInput schema / properties / file_name / description
      Previous value: -"File name including extension (e.g. \"screenshot.png\")"New value: +"File name including extension (e.g. \"screenshot.png\"). Optional with file_path (defaults to the file's own name)."
    • addedInput schema / properties / file_path
      Added value: +{
      +  "description": "Path to a file on the machine running NowAIKit (local stdio server: Claude Desktop, Claude Code, Cursor, etc.). Works on Windows, macOS and Linux: absolute paths (C:\\Users\\me\\report.xlsx, /Users/me/report.xlsx), ~/ paths, file:// URLs, or paths relative to the server's working folder. Secrets (SSH/cloud keys, .env files, credential stores, MCP client configs) are always refused. Not available on remote/hosted servers.",
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "table",
      -  "record_sys_id",
      -  "file_name"
      -]New value: +[
      +  "table",
      +  "record_sys_id"
      +]
  2. Changed6 schema fields changedv4.15.1
    • changedInput schema / properties / content_base64 / description
      Previous value: -"Base64-encoded file content (use standard base64 encoding)"New value: +"Base64-encoded file content. Only for small files. Use source_url for anything larger."
    • changedInput schema / properties / content_type / description
      Previous value: -"MIME type (e.g. \"image/png\", \"application/pdf\", \"text/plain\", \"application/json\")"New value: +"MIME type (e.g. \"image/png\", \"application/pdf\"). Optional when source_url is used (inferred from the response or file extension)."
    • addedInput schema / properties / source_auth_header
      Added value: +{
      +  "description": "Optional Authorization header value sent when fetching source_url (e.g. \"Bearer <token>\" or \"Basic <creds>\") for any protected URL that requires authentication.",
      +  "type": "string"
      +}
    • addedInput schema / properties / source_url
      Added value: +{
      +  "description": "PREFERRED. http(s) URL the server fetches the file from and attaches directly. Use this for anything larger than a few hundred KB. Bytes never travel through this tool call.",
      +  "type": "string"
      +}
    • changedInput schema / properties / table / description
      Previous value: -"Table name (e.g. \"incident\")"New value: +"Table name (e.g. \"incident\", \"kb_knowledge\")"
    • changedInput schema / required
      Previous value: -[
      -  "table",
      -  "record_sys_id",
      -  "file_name",
      -  "content_type",
      -  "content_base64"
      -]New value: +[
      +  "table",
      +  "record_sys_id",
      +  "file_name"
      +]
  3. First observedv1.0.2

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond the annotations by disclosing the WRITE_ENABLED=true prerequisite, the refusal of secrets/credential files, and the sha256 + size_bytes integrity response. One gap remains: with destructiveHint=false and idempotentHint=false declared, the description does not state whether re-uploading the same file creates a duplicate attachment or overwrites — relevant for a non-idempotent write.

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?

Dense and front-loaded with zero filler sentences; every clause carries operational meaning. The parenthetical justification about model output limits is slightly wordier than needed but reinforces the size guidance rather than repeating it.

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?

There is no output schema, and the description compensates by naming the returned fields (sha256, size_bytes). Combined with the prerequisite flag, secret-refusal policy, and size thresholds, an agent has everything needed to call this write 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 coverage is 100%, so the baseline is 3, but the description adds a genuine cross-parameter constraint absent from the schema: exactly one of file_path, source_url, content_base64 must be supplied. It also supplies the size heuristic that motivates preferring the non-base64 paths.

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

Purpose5/5

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

States a specific verb and resource ("Attach a file to a ServiceNow record") and names the target record field, so it is immediately distinguishable from siblings like read_attachment or copy_attachment. The purpose sentence is front-loaded and unambiguous.

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

Usage Guidelines5/5

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

Explicitly tells the agent to provide ONE of three mutually exclusive input modes and gives the selection rule: prefer file_path/source_url for anything over ~20KB, content_base64 only for small files. It also flags file_path as local-server-only, which effectively rules it out for hosted deployments.

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

Deploy Server

Other Tools