Valet

Publish an agent

publish_agent

Destructive

Publish source as an agent: a SOUL.md describing who it is, a valet.yaml declaring the skills, connectors, channels, and configuration it runs with, and any supporting files. Use it when the work is an agent that answers on a channel or runs on a schedule, not a website or an app. Apply the governance skill before calling.

Send the agent one of two ways. files carries it in the call, which works from any client. push: {id, commit} publishes a commit you pushed with git: call create_push, run the recipe it returns, then pass the push_id and the commit sha it prints. Use push when you can run git with network access or when you changed a clone of the agent's source; a push that builds on a main that has since moved is merged onto it as a deploy is. Pass files or push, not both.

The tree, in files or in the commit, must include valet.yaml and SOUL.md at the root. Unlike a website's or an app's, an agent's valet.yaml is yours: Valet validates it rather than writing it, and refuses one the agent rules reject. An organization connector or channel the manifest names is attached for you. When the manifest names one the organization does not have, or a skill that does not resolve, nothing deploys and the answer lists what is pending and the tool that sets each up; do that and call again with the same files.

Publishing changes an agent that exists: create it first with create_service (kind: agent), then publish to its name. A name that holds no agent is refused. Publishing replaces the agent's source with these files, so read get_source first when the agent is not yours. An agent deploy finishes before this call returns: the answer carries the release version, and get_service reports whether the agent is running and what it holds. In an organization with release policies, the answer may carry evaluation instead of a version: the release is built and waits for its policies, and get_evaluation with wait_seconds 20 follows it. Requires connecting a Valet account.

Input Schema

Name	Required	Description
`name`	Yes	Required. The agent's name. The agent must exist: create it first with create_service. Publishing to it replaces its source.
`push`	No	Publish a Git push instead of files: the id create_push returned and the commit you pushed to its branch. Use it when you can run git with network access, because it sends only what changed. Pass files or push, not both; every other argument keeps its meaning.
`files`	No	Required unless push is given. The agent's files, [{path, content}], including valet.yaml and SOUL.md at the root.
`org_name`	No	The Valet organization to publish into. Omit to use the organization the account joined first.
`discard_draft`	No	Set true to discard an open draft on this agent that another session left. Omit to be told about it instead. Not used with push.
`idempotency_key`	No	An opaque key of your choosing. Repeating a call with the same key returns the first call's result instead of deploying a second release. Use a new key for new files: a repeated key returns the earlier result even when the files changed. A call that deployed nothing gives its key back.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 16, 2026

changedInput schema / properties / discard_draft / description

Previous value: -"Set true to discard an open draft on this agent that another session left. Omit to be told about it instead."New value: +"Set true to discard an open draft on this agent that another session left. Omit to be told about it instead. Not used with push."

changedInput schema / properties / files / description

Previous value: -"Required. The agent's files, [{path, content}], including valet.yaml and SOUL.md at the root."New value: +"Required unless push is given. The agent's files, [{path, content}], including valet.yaml and SOUL.md at the root."

changedInput schema / properties / name / description

Previous value: -"Required. The agent's name. Naming an agent that exists republishes it."New value: +"Required. The agent's name. The agent must exist: create it first with create_service. Publishing to it replaces its source."

addedInput schema / properties / push

Added value: +{
+  "description": "Publish a Git push instead of files: the id create_push returned and the commit you pushed to its branch. Use it when you can run git with network access, because it sends only what changed. Pass files or push, not both; every other argument keeps its meaning.",
+  "properties": {
+    "commit": {
+      "description": "Required. The full sha of the commit you pushed to the push's branch. The recipe create_push returned prints it.",
+      "type": "string"
+    },
+    "id": {
+      "description": "Required. The push_id create_push returned.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "commit"
+  ],
+  "type": "object"
+}

changedInput schema / required

Previous value: -[
-  "name",
-  "files"
-]New value: +[
+  "name"
+]

AddedOct 8, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description goes well beyond them: it discloses that publishing REPLACES the agent's source, that a deploy completes before the call returns, that a name with no agent is refused, that unresolved skills/connectors abort the deploy and return a pending list, and that release-policy orgs return an evaluation instead of a version. It also states the auth requirement ('Requires connecting a Valet account').

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?

Front-loaded with the purpose and the routing rule in the first sentence, then organized into clear paragraphs (modes, tree requirements, mutation semantics). It is long, and a few clauses (e.g., the idempotency-key restatement, the merge-on-moved-main detail) could be trimmed, but nearly every sentence earns its place.

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 complex, destructive, no-output-schema tool this covers everything an agent needs: prerequisite creation, both payload modes, required file layout, failure behavior, return shape ('the answer carries the release version'), and the follow-up path (get_service, get_evaluation with wait_seconds 20). No output schema is needed because returns are described.

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 schema already documents each field; the baseline would be 3. The description adds real meaning on top: it explains the files-vs-push mutual exclusivity ('Pass files or push, not both'), the full push workflow (create_push → run recipe → pass push_id and commit sha), and that valet.yaml/SOUL.md must be at the root. That exceeds what the schema alone conveys.

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 ('Publish source as an agent') and immediately scopes it against siblings: 'when the work is an agent that answers on a channel or runs on a schedule, not a website or an app.' An agent can distinguish this from publish_app, publish_site, and publish_skill without opening any 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?

Gives explicit when-to-use ('agent that answers on a channel or runs on a schedule'), when-not (website or app), a required prerequisite ('Apply the governance skill before calling', 'create it first with create_service'), and a decision rule between the two modes ('Use push when you can run git with network access...'). Nothing about routing is left to inference.

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

All Valet tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?