Skip to main content
Glama

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 user wants an agent on Valet that answers on a channel or runs on a schedule. Read the organization's requirements with get_skill governance before calling. A policy set to block refuses a publish that fails it, and the answer names what to fix; a monitor policy only records findings, which get_evaluation lists.

files carries the agent in the call, from any client. push: {id, commit} publishes a commit you pushed after create_push, with the sha its recipe prints; use it when you can run git with network access or changed a clone of the agent's source. A push built on a main that has since moved is merged onto it as a deploy is, and one whose tree is already deployed answers no_changes, as do files the agent already runs.

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, but not a Slack channel, which a person sets up, or one whose attach failed. When the manifest names one that is missing or not attached, or a skill that does not resolve, nothing deploys and pending lists each with the tool that sets it up; call again with the same files after.

Publishing changes an agent that exists: create it first with create_service (kind: agent), then publish to its name. 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 follows it. Requires connecting a Valet account.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>"
    },
    "name": "publish_agent"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesThe agent's name. The agent must exist: create it first with create_service. Publishing to it replaces its source.
pushNoPublish 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. Every other argument keeps its meaning.
filesNoThe agent's source sent in the call: valet.yaml and SOUL.md at the root, and any supporting files. For a Git push, pass push instead.
org_nameNoThe Valet organization to publish into. Omit to use the organization the account joined first.
discard_draftNoSet 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_keyNoAn 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.

Output Schema

NameRequiredDescriptionDefault
orgYesName of the Valet organization the call acted in.
nameYesName of the agent.
pendingNoWhat the organization must set up before the agent deploys. Nothing deployed. Set each up with its tool, then call publish_agent again with the same files. Absent when the publish went through.
versionNoVersion number of the release the publish activated. Absent when nothing deployed: the call is pending (see pending), the release waits for its policies (see evaluation), or nothing changed.
evaluationNoThe release evaluation. Without version, the release is built and waits for its policies: follow it with get_evaluation. With version, the release is live and this is its monitor-only evaluation. Absent when the release has none.
no_changesNoTrue when the files or pushed tree are what the agent already runs, so nothing deployed. Absent otherwise.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / no_changes / description
      Previous value: -"True when the pushed tree is what the agent already runs, so nothing deployed. Absent otherwise."New value: +"True when the files or pushed tree are what the agent already runs, so nothing deployed. Absent otherwise."
  2. Changed1 schema field changed
    • changedInput schema / properties / files / description
      Previous value: -"The agent's files. Give this or push, not both. valet.yaml and SOUL.md at the root are required."New value: +"The agent's source sent in the call: valet.yaml and SOUL.md at the root, and any supporting files. For a Git push, pass push instead."
  3. Changed1 schema field changed
    • changedInput schema / properties / push / description
      Previous value: -"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."New value: +"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. Every other argument keeps its meaning."
  4. Changed3 schema fields changed
    • changedOutput schema / properties / evaluation / properties / deploy_message / description
      Previous value: -"The refusal's message when deploy refused the release. Absent otherwise."New value: +"The refusal's message when deploy refused the release, with credentials redacted as [redacted]. Absent otherwise."
    • addedOutput schema / properties / evaluation / properties / redactions
      Added value: +{
      +  "description": "How many credentials were replaced with [redacted] in the text this answer was built from: secret values the service holds, and strings shaped like an API key, a private key, a token, or a password in a URL or header. Redaction is best effort, so 0 does not prove the text holds no credential.",
      +  "type": "integer"
      +}
    • changedOutput schema / properties / evaluation / required
      Previous value: -[
      -  "id",
      -  "status"
      -]New value: +[
      +  "id",
      +  "status",
      +  "redactions"
      +]
  5. Changed1 schema field changed
    • changedOutput schema / properties / pending / properties / attach / description
      Previous value: -"Connectors and channels the organization has but the agent does not hold. Attach each to the agent."New value: +"Connectors and channels the organization has but the agent does not hold, because publishing could not attach them: a Slack channel, which a person sets up, or one whose attach failed. Attach each to the agent."
  6. Changed1 schema field changed
    • changedInput schema / properties / files / items / properties / path / description
      Previous value: -"Path relative to the agent root, with '/' separators and no leading slash. It may not contain '.' or '..' segments."New value: +"Path of the file relative to the agent root, such as docs/guide.md."
  7. Changed28 schema fields changed
    • changedInput schema / properties / files / description
      Previous value: -"Required unless push is given. The agent's files, [{path, content}], including valet.yaml and SOUL.md at the root."New value: +"The agent's files. Give this or push, not both. valet.yaml and SOUL.md at the root are required."
    • changedInput schema / properties / files / items / properties / content / description
      Previous value: -"Required. The file's complete text content."New value: +"The file's complete text content."
    • changedInput schema / properties / files / items / properties / path / description
      Previous value: -"Required. The file's path, relative to the agent root."New value: +"Path relative to the agent root, with '/' separators and no leading slash. It may not contain '.' or '..' segments."
    • changedInput schema / properties / name / description
      Previous value: -"Required. The agent's name. The agent must exist: create it first with create_service. Publishing to it replaces its source."New value: +"The agent's name. The agent must exist: create it first with create_service. Publishing to it replaces its source."
    • addedInput schema / properties / name / maxLength
      Added value: +63
    • addedInput schema / properties / name / minLength
      Added value: +3
    • addedInput schema / properties / name / pattern
      Added value: +"^[A-Za-z0-9][A-Za-z0-9-]{1,61}[A-Za-z0-9]$"
    • changedInput schema / properties / push / properties / commit / description
      Previous value: -"Required. The full sha of the commit you pushed to the push's branch. The recipe create_push returned prints it."New value: +"The full sha of the commit you pushed to the push's branch. The recipe create_push returned prints it."
    • changedInput schema / properties / push / properties / id / description
      Previous value: -"Required. The push_id create_push returned."New value: +"The push_id create_push returned."
    • addedOutput schema / properties / evaluation / description
      Added value: +"The release evaluation. Without version, the release is built and waits for its policies: follow it with get_evaluation. With version, the release is live and this is its monitor-only evaluation. Absent when the release has none."
    • addedOutput schema / properties / evaluation / properties / deploy / description
      Added value: +"What deploy did with the release: 'waiting' for the policies, 'live', or the code of the refusal. Absent when deploy has not decided."
    • addedOutput schema / properties / evaluation / properties / deploy_message / description
      Added value: +"The refusal's message when deploy refused the release. Absent otherwise."
    • addedOutput schema / properties / evaluation / properties / id / description
      Added value: +"ID of the release evaluation. Pass it to get_evaluation as evaluation_id."
    • addedOutput schema / properties / evaluation / properties / monitor_findings / description
      Added value: +"Count of findings monitor policies reported on a live release. They never block it; get_evaluation shows each. Absent when zero."
    • addedOutput schema / properties / evaluation / properties / monitor_running / description
      Added value: +"Names of monitor policies still pending or running on a live release. They never block it. Absent when none are."
    • addedOutput schema / properties / evaluation / properties / status / description
      Added value: +"Status of the evaluation across its release policies. get_evaluation lists the per-policy results."
    • addedOutput schema / properties / name / description
      Added value: +"Name of the agent."
    • addedOutput schema / properties / no_changes / description
      Added value: +"True when the pushed tree is what the agent already runs, so nothing deployed. Absent otherwise."
    • addedOutput schema / properties / org / description
      Added value: +"Name of the Valet organization the call acted in."
    • addedOutput schema / properties / pending / description
      Added value: +"What the organization must set up before the agent deploys. Nothing deployed. Set each up with its tool, then call publish_agent again with the same files. Absent when the publish went through."
    • addedOutput schema / properties / pending / properties / attach / description
      Added value: +"Connectors and channels the organization has but the agent does not hold. Attach each to the agent."
    • addedOutput schema / properties / pending / properties / attach / items / properties / catalog / description
      Added value: +"The catalog entry the manifest names for it."
    • addedOutput schema / properties / pending / properties / attach / items / properties / kind / description
      Added value: +"Whether the dependency is a 'connector' or a 'channel'."
    • addedOutput schema / properties / pending / properties / install / description
      Added value: +"Connectors and channels the manifest names that the organization has no instance of. Create each from its catalog entry."
    • addedOutput schema / properties / pending / properties / install / items / properties / catalog / description
      Added value: +"The catalog entry the manifest names for it."
    • addedOutput schema / properties / pending / properties / install / items / properties / kind / description
      Added value: +"Whether the dependency is a 'connector' or a 'channel'."
    • addedOutput schema / properties / pending / properties / skills / description
      Added value: +"Skill references in the manifest that do not resolve."
    • addedOutput schema / properties / version / description
      Added value: +"Version number of the release the publish activated. Absent when nothing deployed: the call is pending (see pending), the release waits for its policies (see evaluation), or nothing changed."
  8. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "evaluation": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "deploy": {
      +          "type": "string"
      +        },
      +        "deploy_message": {
      +          "type": "string"
      +        },
      +        "id": {
      +          "type": "string"
      +        },
      +        "monitor_findings": {
      +          "type": "integer"
      +        },
      +        "monitor_running": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": [
      +            "null",
      +            "array"
      +          ]
      +        },
      +        "status": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "id",
      +        "status"
      +      ],
      +      "type": [
      +        "null",
      +        "object"
      +      ]
      +    },
      +    "name": {
      +      "type": "string"
      +    },
      +    "no_changes": {
      +      "type": "boolean"
      +    },
      +    "org": {
      +      "type": "string"
      +    },
      +    "pending": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "attach": {
      +          "items": {
      +            "additionalProperties": false,
      +            "properties": {
      +              "catalog": {
      +                "type": "string"
      +              },
      +              "kind": {
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "kind",
      +              "catalog"
      +            ],
      +            "type": "object"
      +          },
      +          "type": [
      +            "null",
      +            "array"
      +          ]
      +        },
      +        "install": {
      +          "items": {
      +            "additionalProperties": false,
      +            "properties": {
      +              "catalog": {
      +                "type": "string"
      +              },
      +              "kind": {
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "kind",
      +              "catalog"
      +            ],
      +            "type": "object"
      +          },
      +          "type": [
      +            "null",
      +            "array"
      +          ]
      +        },
      +        "skills": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": [
      +            "null",
      +            "array"
      +          ]
      +        }
      +      },
      +      "type": [
      +        "null",
      +        "object"
      +      ]
      +    },
      +    "version": {
      +      "maximum": 2147483647,
      +      "minimum": -2147483648,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "org",
      +    "name"
      +  ],
      +  "type": "object"
      +}
  9. Changed5 schema fields changed
    • 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"
      +]
  10. Added

TDQS

A4.8/5.0
Behavior5/5

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

Goes well past the annotations by disclosing what block vs monitor policies do to the result, that missing connectors/channels/skills stop the deploy and surface via 'pending', that a moved main triggers a merge, that no_changes is a legitimate outcome, that the deploy finishes before return, and that release-policy orgs return an evaluation instead of a version. These are exactly the failure/recovery semantics an agent needs and none are in the structured fields.

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 purpose and the manifest concept before any edge cases, and every paragraph carries load. It is still dense and long, with some convoluted phrasing ('merged onto it as a deploy is') and a few facts restated from the schema, so it is not maximally tight.

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?

An output schema exists, yet the description still tells the agent what the answer contains (release version, evaluation, no_changes, pending lists) and how to follow up with get_service/get_evaluation. For a destructive, multi-mode publish with nested parameters, nothing material is left unexplained.

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 baseline is 3, but the description adds real meaning: why push exists ('sends only what changed'), how push interacts with concurrency (merge onto a moved main) and with discard_draft ('Not used with push'), and the retry loop of re-calling with the same files after fixing pending items. It says nothing about org_name or idempotency_key beyond the schema, which caps it at 4.

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?

Opens with a specific verb and resource plus the exact payload shape (SOUL.md, valet.yaml, supporting files), which no sibling does. It also draws the key boundary against create_service ('create it first with create_service (kind: agent), then publish to its name') and implicitly against publish_app/publish_site by scoping to agents.

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?

Explicit when-to-use ('when the user wants an agent on Valet that answers on a channel or runs on a schedule'), a prerequisite call ('read the organization's requirements with get_skill governance before calling'), a read-first rule ('read get_source first when the agent is not yours'), and a files-vs-push selection rule based on git/network access. Alternatives are named rather than implied.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources