Skip to main content
Glama
dnotitia

akb

by dnotitia
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

akb_put_file

Upload a local file to a vault's S3-backed storage for PDFs, images, datasets, or binary content too large for regular text entries. Returns a canonical URI for later retrieval, update, or deletion.

Instructions

Upload a local file to a vault's file storage (S3-backed). Use for PDFs, images, datasets, or any binary content too large for akb_put. Response includes the canonical uri — akb://{vault}/coll/{collection}/file/{uuid} when stored under a collection, or akb://{vault}/file/{uuid} at the vault root — pass that to akb_get_file / akb_update_file / akb_delete_file. MIME type is auto-detected from the filename extension unless overridden.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
vaultNoVault name. Required unless `parent` is given.
parentNoParent location as a canonical URI — `akb://{vault}` for the vault root, `akb://{vault}/coll/{path}` for a collection. When given, the file is uploaded there and `vault`/`collection` are derived from the URI.
file_pathYesAbsolute path to the local file to upload
mime_typeNoMIME type of the file (e.g. 'text/html', 'application/pdf', 'image/png'). Optional — if omitted, it is auto-detected from the filename extension. Override only when the extension is missing, ambiguous, or wrong.
collectionNoLogical grouping (like document collections). Ignored when `parent` is given.
descriptionNoBrief description of the file
_vault_skill_ackNoOpaque acknowledgement from vault_skill.ack_token. Apply the guide, then retry the unchanged operation with this value. The bundled proxy fills it on an exact retry.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.0.14
    • addedInput schema / properties / _vault_skill_ack
      Added value: +{
+  "description": "Opaque acknowledgement from vault_skill.ack_token. Apply the guide, then retry the unchanged operation with this value. The bundled proxy fills it on an exact retry.",
+  "maxLength": 128,
+  "type": "string"
+}
  2. Changed4 schema fields changedv2.0.6
    • changedInput schema / properties / collection / description
      Previous value: -"Logical grouping (like document collections)"New value: +"Logical grouping (like document collections). Ignored when `parent` is given."
    • addedInput schema / properties / parent
      Added value: +{
+  "description": "Parent location as a canonical URI — `akb://{vault}` for the vault root, `akb://{vault}/coll/{path}` for a collection. When given, the file is uploaded there and `vault`/`collection` are derived from the URI.",
+  "type": "string"
+}
    • changedInput schema / properties / vault / description
      Previous value: -"Vault name (new files are not URI-addressable yet, so the placement vault is named explicitly)"New value: +"Vault name. Required unless `parent` is given."
    • changedInput schema / required
      Previous value: -[
-  "vault",
-  "file_path"
-]New value: +[
+  "file_path"
+]
  3. Addedv2.0.4
  4. Removedv2.0.1
  5. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

No annotations exist, so the description carries the full disclosure burden — and it delivers: it reveals the S3 backing, the exact response contract (`akb://{vault}/coll/{collection}/file/{uuid}` vs `akb://{vault}/file/{uuid}`), the recommended follow-up tools (akb_get_file / akb_update_file / akb_delete_file), and MIME auto-detection behavior. It falls short only on edge behaviors like overwrite semantics or permission prerequisites.

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 with zero filler. The primary action is front-loaded in sentence one, the response contract and chaining strategy are compactly packed into sentence two, and the MIME behavior closes it out. Every sentence 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?

For a 7-parameter upload tool with no output schema and no annotations, the description is unusually complete: it covers purpose, selection criteria, return contract, follow-up routing, and a default-behavior override. The only notable gaps are preconditions (vault existence, write access) and whether re-uploading to the same location overwrites — minor for a tool whose params are already fully documented in the schema.

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 baseline is 3. The description elevates this by illustrating how the parent/vault/collection parameters map to the two possible canonical uri shapes, which the individual schema entries don't tie together. The MIME sentence partly duplicates the mime_type parameter description, so the net added value is moderate rather than large.

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: 'Upload a local file to a vault's file storage (S3-backed).' It distinguishes itself from the closest sibling akb_put by targeting 'any binary content too large for akb_put,' so an agent can tell them apart without opening the schema.

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?

'Use for PDFs, images, datasets, or any binary content too large for akb_put' explicitly names the alternative tool and the condition that selects this one. The 'too large' qualifier implies the exclusion case (small or textual content belongs in akb_put), giving clear when-to-use guidance.

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