Skip to main content
Glama
Rootly MCP server

Rootly MCP server

Official
by rootlyhq

Update Ai Skill

update_ai_skill
DestructiveIdempotent

Update an AI skill's attributes so changes apply to every agent and automation that loads the skill.

Instructions

Change an AI skill. Only the attributes you send change, and the change applies to every agent and automation that loads the skill. An AI skill is reusable written guidance (markdown body) that Rootly AI agents, users and AI automations can load while they work. Skills keep saved versions, readable with list_ai_skill_versions.

Requires OAuth scope ai.skills:write. Read-only attributes are ignored on write.

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": {
      "id": "<id>",
      "data": "<data>"
    },
    "name": "update_ai_skill"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesThe skill ID or slug.
dataYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv3.0.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare destructive=true, idempotent=true, and non-read-only, so the safety profile is covered structurally. The description adds genuine context beyond that: the blast radius ('applies to every agent and automation that loads the skill'), the recoverability path (saved versions readable via list_ai_skill_versions), and the required OAuth scope 'ai.skills:write'. It stops short of describing failure modes or what the response contains.

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?

Opens with the operation, then scoping, then the domain definition, then the auth requirement — a sensible front-loaded order with little filler. The mid-paragraph definition of an AI skill is slightly verbose for a caller that has the sibling catalog, but it earns its place by clarifying what 'change' affects.

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 destructive, nested-object mutation with an output schema present, the description covers what is needed: partial-update semantics, blast radius, version recovery, and auth scope. Return values need not be explained because an output schema exists, and the remaining schema gaps are minor.

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?

With only 50% schema description coverage, the description compensates by explaining the two most consequential semantics: partial updates (unsent attributes are preserved) and that read-only attributes are silently ignored on write. It also clarifies that `body` is markdown. The id/data.id coupling is left to the schema, which already documents it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Change an AI skill') and then defines what an AI skill is (reusable markdown guidance loaded by agents, users, automations), which lets an agent distinguish it from the version-listing sibling. It does not explicitly contrast itself with create_ai_skill, so sibling routing is implied rather than spelled out.

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

Usage Guidelines3/5

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

The description gives partial-update semantics ('Only the attributes you send change') and points to list_ai_skill_versions for reading saved versions, which is useful situational guidance. It never states when to use create_ai_skill instead, or any precondition such as needing an existing skill ID, so usage is implied rather than enumerated.

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

Deploy Server

Other Tools