Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentvolumes.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

A Tool component packages a function or API capability that an agent calls during task execution. When an agent decides it needs to search for papers, read a file, fetch a URL, or execute a shell command, it reaches for a tool. Tools are stateless per invocation — each call is independent — and are always agent-initiated, not user-triggered.

​
Tool vs. Command

The key distinction is who initiates the call:
ToolCommand
Invoked byAgent (programmatically)User (explicitly)
TriggerFunction call by agentSlash command pattern
InputStructured parametersUser-provided context
StatefulnessStateless per callMay maintain workflow state
If a user types a slash command to invoke it, use a Command. If an agent calls it as a function during its task loop, use a Tool.

​
Entrypoint format

Tool entrypoints can be:
  • JSON (.json) — a function descriptor object
  • YAML (.yaml) — a function descriptor object
  • Executable script — any regular executable file
The portable validation minimum requires:
  • JSON and YAML descriptor entrypoints must exist and parse successfully.
  • Script entrypoints must exist and be regular files. Host executability and local policy are checked at load time, not during portable validation.
Agent Volumes v0.1 does not standardize a full tool ABI. If your entrypoint is a JSON or YAML descriptor and it includes name and inputSchema fields, those are interpreted as function-description metadata. The spec does not define the complete execution contract — that remains runtime-local.

​
Declaring a tool in volume.toml

Add a [[components]] entry with type = "tool" and point entrypoint to your tool descriptor or script. 
[[components]]
type = "tool"
name = "arxiv-search"
entrypoint = "./tools/arxiv-search.json"
description = "Search arXiv for papers by query, author, or category"

​
JSON descriptor example

A JSON tool descriptor describes the function’s name, what it does, and the shape of its inputs: 
{
  "name": "arxiv-search",
  "description": "Search arXiv for academic papers by query string, author name, or category.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query string"
      },
      "category": {
        "type": "string",
        "description": "arXiv category (e.g., cs.AI, math.CO)"
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of results to return",
        "default": 10
      }
    },
    "required": ["query"]
  }
}

​
Portable capability classes

Agent Volumes describes tools in terms of portable capability classes — stable cross-runtime concepts that work regardless of which runtime loads your volume. When you design a tool, consider which capability class it belongs to:
Capability classTypical permission requirements
Shell executionshell = "allow"
File readfilesystem = "read"
File write/editfilesystem = "write" or "read-write"
File discoveryfilesystem = "read"
Content searchfilesystem = "read"
Web fetchnetwork = "read"
Web searchnetwork = "read"
Code intelfilesystem = "read"
External bridgenetwork, shell, or both
DelegationDepends on the delegated tool’s permissions
Runtime-specific tool names like Bash, WebFetch, or run_shell_command are profile-facing names. The portable capability class is what matters for cross-runtime compatibility.

​
Permissions for tools

Declare the permissions your tool needs. Most tools require either filesystem or network access — or both. 
[[components]]
type = "tool"
name = "arxiv-search"
entrypoint = "./tools/arxiv-search.json"
description = "Search arXiv for papers by query, author, or category"
providers = ["arxiv"]

[components.permissions]
network = "read"
For a tool that reads and writes files: 
[[components]]
type = "tool"
name = "file-editor"
entrypoint = "./tools/file-editor.json"
description = "Read and edit files in the working directory"

[components.permissions]
filesystem = "read-write"
Component permissions can only be equal to or narrower than the volume-level permissions. Declaring shell = "allow" at the component level when the volume declares shell = "deny" is a validation failure.

​
Complete volume example with tools

[volume]
schema = 1
name = "research-agent-pack"
version = "1.4.0"
description = "Research assistant plugin with literature analysis tools"
license = "Apache-2.0"
role = "plugin"
providers = ["arxiv", "semantic-scholar"]

[publisher]
id = "example"

[[components]]
type = "tool"
name = "arxiv-search"
entrypoint = "./tools/arxiv-search.json"
description = "Search arXiv for papers by query, author, or category"
providers = ["arxiv"]

[[components]]
type = "tool"
name = "semantic-scholar-lookup"
entrypoint = "./tools/semantic-scholar.json"
description = "Look up paper details and citation counts from Semantic Scholar"
providers = ["semantic-scholar"]

[permissions]
network = "read"
filesystem = "deny"
shell = "deny"

​
Component identifier

Once published, reference the tool using a purl identifier: 
pkg:volume/research-agent-pack@1.4.0#tool/arxiv-search
Other components can declare a dependency on this tool: 
[component-dependencies]
"literature-reviewer" = [
  "pkg:volume/research-agent-pack#tool/arxiv-search",
]