Manifest and Schemas

The manifest is your tool’s contract. It tells Valdr what the tool is called, which files it needs, how to start it, and exactly what each action accepts and returns. Because the contract is explicit, the Builder can offer the right input fields, Valdr can reject bad input before your code runs, and later steps can rely on the output shape.

Start with the working example, then use this page to look up a field.

The manifest at a glance

A manifest file ends in .tool.yaml, .tool.yml, or .tool.json and lives in a folder the pack includes. The finished example looks like this:

my-tools/
  pack.yaml
  tools/
    text/
      text.tool.yaml
      main.mjs

Supported icons are command-line, code-bracket, code-bracket-square, variable, cube, cpu-chip, server-stack, cloud, ticket, and document-text. An omitted or unknown name uses the default tool icon.

The pack’s version and the tool’s revision are separate. Bump the tool revision whenever anything in the manifest or its listed files changes; Valdr rejects changed content under a revision it has already imported, even if that revision was removed from the catalog. Renaming a tool ID creates a new tool; workflows that pinned the old ID keep using it.

On each Valdr host, a tool ID belongs to the pack that first imported it. Importing the same ID from a different pack is rejected, even after the owner’s revisions are removed from the catalog, so ship updates from the owning pack and keep its pack value unchanged, or give your tool a new ID.

Actions

One tool can expose many actions from a single program. Valdr sends the chosen action’s id in the request, and your program dispatches on it.

Put related actions in one tool. Use separate tools when programs need different runtimes, environment access, or release schedules.

To list a command you haven’t implemented yet, add it with execution: unsupported and a reason, such as unsupportedReason: "Interactive sign-in must be completed on the host." It stays visible in the Builder with that reason but can’t run.

Files, runtimes, and dependencies

List every file your tool needs under files. Valdr keeps exactly those files, verifies them before every run, and carries them through export and import.

Good to know:

• Arguments that name a listed file become absolute paths to the tool’s retained copy, so main.mjs still works when the step runs in a project folder. Other arguments stay literal, and Valdr never expands shell syntax, variables, or globs.
• A bare executable name is found on the host’s PATH. A relative path containing / resolves inside the tool’s folder.
• Import never installs anything. No package managers, install hooks, or compilers run. Bundle the helper files you need, or document what must be installed on the host. A lockfile alone doesn’t install dependencies.
• Treat the tool’s own folder as read-only. Write output to the working directory, a destination given as input, or a temp folder. In Node, find bundled files with new URL('./asset.json', import.meta.url) and workflow files with process.cwd(). In Python, use Path(__file__).parent and Path.cwd().
• Don’t set process.cwd. The workflow step chooses the working directory.
• Wrapping a CLI? Most CLIs don’t speak the tool protocol, so point executable at an adapter program rather than at gh or aws directly. See Wrap a CLI.

Input and output schemas

Schemas are where the contract gets its teeth. Valdr checks input before your program starts and checks your result before later steps see it.

• Input: inputSchema describes the input object your program receives. Its root must be type: object.
• Output: outputSchema describes only the successful data value, not the whole result envelope. It can be a schema object or true.
• In the Builder: an input schema appears as named fields when its root sets additionalProperties: false, uses only type, properties, required, additionalProperties, title, and description, and every property is a string, number, integer, or boolean. Any other schema, including nested objects and arrays, uses JSON input. Both paths are validated against the same schema.
• No silent fixes: Valdr doesn’t insert defaults, coerce strings to numbers, or strip extra properties. A default annotation is documentation only, so apply defaults in your program.

Use ordinary JSON Schema keywords: type, properties, required, additionalProperties, enum, minimum, maximum, minLength, maxLength, pattern, items, and $defs. For a nullable string, write type: [string, "null"].

Keep schemas specific. outputSchema: true accepts any JSON, but then users can’t count on stable fields to map.

For the summary example, the input is {"text":"Hello Valdr\nTools are ready."} and the successful data is {"characters":28,"words":5,"lines":2}. Both schemas reject extra properties.

Run valdr validate-pack to check your schemas before you import.

Next step

Learn the request and result format your program reads and writes.