Skip to main content
Glama
aartiq

NowAIKit

by aartiq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

upload_attachment

Attach a file to a ServiceNow record via source_url (recommended) or base64 content. Use source_url for large files; base64 only for small files.

Instructions

Attach a file to a ServiceNow record (requires WRITE_ENABLED=true). Provide EITHER source_url (recommended) OR content_base64. source_url has the server fetch the file directly, so large files never pass through this tool call; content_base64 is only reliable for small files (a few hundred KB) and is rejected above ~4MB.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
tableYesTable name (e.g. "incident", "kb_knowledge")
file_nameYesFile name including extension (e.g. "screenshot.png")
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. Changed6 schema fields changedv4.16.0
    • 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"
+]
  2. First observedv4.1.6

TDQS

A4.4/5.0
Behavior5/5

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

The description goes well beyond the annotations by disclosing the write prerequisite, the server-side fetch behavior for source_url, the fact that large files never pass through the tool call, and the ~4MB rejection threshold for content_base64. This is substantive behavioral 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?

Three sentences, each carrying essential information: the action and prerequisite, the two input modes, and the server-fetch advantage. Front-loaded and free of filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with no output schema, the description covers the critical call-correctness information: required precondition, parameter selection, mutual exclusivity of source_url and content_base64, size limits, and large-file behavior. The schema handles the remaining parameter details.

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 already provides 100% description coverage, so baseline is 3. The description adds real value by explaining which parameter is preferred, when content_base64 is unreliable, and the size limit behavior, raising it to a 4.

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 action: 'Attach a file to a ServiceNow record' with a specific verb and target resource. It does not explicitly differentiate from sibling attachment tools like read_attachment or delete_attachment, so it stops short of a 5.

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 guidance on when to use source_url versus content_base64, including size thresholds and the WRITE_ENABLED prerequisite. It does not explicitly contrast this tool with sibling attachment tools, but the parameter-level guidance is strong.

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