Skip to main content
Glama

Detach a skill from an agent

detach_skill
DestructiveIdempotent

Detach a skill from an agent. The skill stays in the organization for other agents, including an organization copy installed from the catalog. Give a built-in's name to detach Valet's default of it. The agent is rebuilt so it stops carrying the skill. Detaching a skill that is not attached changes nothing. Returns the agent and the skill as passed, and not_attached when it was not attached. 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>",
      "skill": "<skill>"
    },
    "name": "detach_skill"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesThe agent's name, as list_services shows it: the agent to detach the skill from.
skillYesThe skill's name, or a ref such as catalog:<name> or org:<name>.
org_nameNoThe Valet organization the agent belongs to. Omit to use the organization the account joined first.

Output Schema

NameRequiredDescriptionDefault
orgYesName of the Valet organization the call acted in.
kindYesKind of the service the skill attaches to. Always agent: skills attach to agents only.
nameYesName of the agent.
skillYesThe skill as you passed it.
not_attachedNoTrue when the skill was not attached and nothing changed. Absent when it was detached.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changed
    • changedInput schema / properties / name / description
      Previous value: -"The agent's name."New value: +"The agent's name, as list_services shows it: the agent to detach the skill from."
    • removedOutput schema / properties / already_attached
      Removed value: -{
      -  "description": "True when attach_skill found the skill already on the agent and changed nothing.",
      -  "type": "boolean"
      -}
    • removedOutput schema / properties / latest_version
      Removed value: -{
      -  "description": "The skill's newest version, which the agent follows. Set by attach_skill; absent when the skill has no version, as a default has none.",
      -  "type": "integer"
      -}
    • changedOutput schema / properties / not_attached / description
      Previous value: -"True when detach_skill found the skill not attached and changed nothing."New value: +"True when the skill was not attached and nothing changed. Absent when it was detached."
    • removedOutput schema / properties / pin_ignored
      Removed value: -{
      -  "description": "True when the skill you gave carried a @v<N> version pin. Pins are retired, so the agent follows the latest version anyway. Set by attach_skill.",
      -  "type": "boolean"
      -}
    • changedOutput schema / properties / skill / description
      Previous value: -"Name of the skill. attach_skill reports the skill's own name; detach_skill repeats what you passed."New value: +"The skill as you passed it."
    • removedOutput schema / properties / source
      Removed value: -{
      -  "description": "Set by attach_skill: org for an organization skill, default for a built-in whose Valet default the agent holds because the organization has published no skill of that name. Absent from detach_skill.",
      -  "type": "string"
      -}
  2. Changed11 schema fields changed
    • changedInput schema / properties / name / description
      Previous value: -"Required. The agent's name."New value: +"The agent's name."
    • changedInput schema / properties / skill / description
      Previous value: -"Required. The skill's name, or a ref such as catalog:<name> or org:<name>."New value: +"The skill's name, or a ref such as catalog:<name> or org:<name>."
    • addedOutput schema / properties / already_attached / description
      Added value: +"True when attach_skill found the skill already on the agent and changed nothing."
    • addedOutput schema / properties / kind / description
      Added value: +"Kind of the service the skill attaches to. Always agent: skills attach to agents only."
    • addedOutput schema / properties / latest_version / description
      Added value: +"The skill's newest version, which the agent follows. Set by attach_skill; absent when the skill has no version, as a default has none."
    • addedOutput schema / properties / name / description
      Added value: +"Name of the agent."
    • addedOutput schema / properties / not_attached / description
      Added value: +"True when detach_skill found the skill not attached and changed nothing."
    • addedOutput schema / properties / org / description
      Added value: +"Name of the Valet organization the call acted in."
    • addedOutput schema / properties / pin_ignored / description
      Added value: +"True when the skill you gave carried a @v<N> version pin. Pins are retired, so the agent follows the latest version anyway. Set by attach_skill."
    • addedOutput schema / properties / skill / description
      Added value: +"Name of the skill. attach_skill reports the skill's own name; detach_skill repeats what you passed."
    • addedOutput schema / properties / source / description
      Added value: +"Set by attach_skill: org for an organization skill, default for a built-in whose Valet default the agent holds because the organization has published no skill of that name. Absent from detach_skill."
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "already_attached": {
      +      "type": "boolean"
      +    },
      +    "kind": {
      +      "type": "string"
      +    },
      +    "latest_version": {
      +      "type": "integer"
      +    },
      +    "name": {
      +      "type": "string"
      +    },
      +    "not_attached": {
      +      "type": "boolean"
      +    },
      +    "org": {
      +      "type": "string"
      +    },
      +    "pin_ignored": {
      +      "type": "boolean"
      +    },
      +    "skill": {
      +      "type": "string"
      +    },
      +    "source": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "org",
      +    "name",
      +    "kind",
      +    "skill"
      +  ],
      +  "type": "object"
      +}
  4. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare destructive=true and idempotent=true, and the description adds genuinely new behavior: the skill persists in the organization, the agent is rebuilt, no-op semantics when the skill was not attached, the not_attached marker, and the Valet account connection requirement. That is well beyond what the structured fields convey.

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?

Six short sentences, front-loaded with purpose and consequence before edge cases. The return-value sentence loosely duplicates the existing output schema, which is the only mildly wasteful element.

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?

Given an output schema, full parameter coverage, and rich annotations, the description covers everything else an agent needs: auth prerequisite, side effects, idempotent no-op outcome, and where the skill ends up. Nothing material is missing for correct invocation.

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 meaning the schema lacks: passing a built-in's name detaches Valet's default of that skill, which is a non-obvious interpretation of the 'skill' parameter. The org_name defaulting behavior is left to the schema, so it stops short of a 5.

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 opening sentence gives a specific verb and resource ('Detach a skill from an agent'), and the second sentence immediately scopes the consequence ('The skill stays in the organization'), which separates it from destroy_* siblings and from attach_skill. An agent can pick this tool without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It supplies clear usage context: use a built-in's name to remove Valet's default, and detaching a non-attached skill is a no-op. It does not name alternatives such as attach_skill or destroy_resource, so there are no explicit exclusions, but the operating conditions are unambiguous.

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