Skip to main content
Glama

improve_agent

Destructive

Refines an existing Claude Code agent by collecting specialist reviews of gaps, skills and cuts, then drafting and saving an improved definition while preserving identity.

Instructions

Refine an existing Claude Code agent in one call, preserving its identity and useful instructions. By default the target reviews itself candidly; add specialists with with or inherit participants/discussion via from_session (the id of a live collaboration or meeting, or of any ended session in the archive). They suggest gaps, replacements, skills and cuts; an architect drafts the definition, participants review independently, and the architect revises if needed. The target is an agent name or a .md path inside the agents directory, /.claude/agents, ~/.claude/agents or a directory listed in ROUNDTABLE_AGENT_PATHS. write: false previews without writes. Frontmatter is read the way Claude Code reads it, including one quoting and leading-tab recovery pass. Exactly the keys Claude Code sees are preserved; improve refuses files Claude Code cannot parse or whose frontmatter contains '---' inside a value, with an error asking you to fix the file first. Identity collision checks use the same metadata view. Model output only supplies name/description/model/tools/skills. Only one improve run per target is allowed; a second fails fast: improve_agent is already running for ; wait for it to finish. Default write: true saves .bak-, then atomically replaces via a temp file and rename, keeping the original mode. If the target changed, was renamed or was deleted during the run it is not overwritten: changes go to .proposed-, which is not an agent file and keeps the original mode; next explains recovery. Creation includes the destination project's .claude/skills in lookup even when the configured skills directory differs. Skill lookup follows Claude Code precedence: personal ~/.claude/skills, then .claude/skills beside the agent file when it is in .claude/agents, then ROUNDTABLE_SKILLS_DIR. Any skill found is reused, never overwritten or shadowed. New skills go beside a target in .claude/agents to its project's .claude/skills only if neither .claude nor .claude/skills is a symlink and the skills realpath stays inside the project. Otherwise they fall back to ROUNDTABLE_SKILLS_DIR with a warning. Results report file realpaths, warnings and next instructions. Tools fail closed: a list with no allowlisted matches or a value of the wrong type is rejected and the architect retries once. Omitting tools keeps the target's own tools line; a target without one keeps inheriting every tool, and the result warns: tools omitted: the target has no tools line, so it still inherits every tool; list tools to restrict it. Public workshops post contributions, reviews and a redacted summary of the final definition (name, description, model, tools, skill names and status, contribution credits, changes and open questions), without its system prompt, skill instructions or descriptions derived from instructions; copied private passages in summary fields are withheld. They never post context, personas, fleet listings or source-session transcripts. Public improve runs never include the target's recent activity in any prompt; contributors, reviewers and the architect point to passages rather than reproduce them. Private improve contributor prompts include recent topics and outcomes from the local activity log.

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": {
      "agent": "<agent>"
    },
    "name": "improve_agent"
  }
}

Input Schema

NameRequiredDescriptionDefault
withNoAdditional specialists; combined with target (when include_self) and from_session participants.
agentYesExisting agent name, or a .md file path inside an allowed agents directory (ROUNDTABLE_AGENTS_DIR, <workspace>/.claude/agents, ~/.claude/agents or ROUNDTABLE_AGENT_PATHS). Written targets are backed up first.
focusNoOptional aspect to improve, such as escalation rules, output quality or missing skills.
modelNoModel id. Defaults: claude-sonnet-5-5 (anthropic), gpt-5.6-luna (openai), zai-org/GLM-5.3 (together), qwen/qwen3-235b-a22b-instruct-2507 (replicate), qwen3:14b (ollama), default (openai_compatible). Model aliases: "opus" (claude-opus-5-5), "sonnet" (claude-sonnet-5-5), "haiku" (claude-haiku-5-5). Replicate accepts owner/name, owner/name:version, or a https://replicate.com/owner/name URL.
writeNoDefault true: back up and update the target. False: preview files and write nothing.
publicNoDefault false. Only set true when the human explicitly asks for a public session. When true, the whole session is posted live to the configured public channel and is world-readable: the topic/agenda, every agent reply, every message you send with say/nudge, and the summary. The context argument is never posted, but agents may paraphrase it in their replies, so keep context generic. Never include personal information, credentials, or private code anywhere in a public session. The result includes public.url so the human can watch live.
roundsNoContribution rounds, default 1, clamped to 1..3.
contextNoOptional background for refinement; never posted publicly.
base_urlNoOnly with provider "openai_compatible": base URL of an OpenAI-compatible /v1 endpoint (e.g. http://localhost:1234/v1). Overrides OPENAI_COMPATIBLE_BASE_URL. OPENAI_COMPATIBLE_API_KEY, if set, is sent only to the OPENAI_COMPATIBLE_BASE_URL origin or one listed in ROUNDTABLE_OPENAI_COMPATIBLE_TRUSTED_ORIGINS; any other base URL gets no Authorization header and must be https (http only to loopback, or to private addresses with ROUNDTABLE_ALLOW_PRIVATE_BASE_URLS=1), never a cloud metadata or (without that setting) private address.
providerNoLLM provider. Default: anthropic. Options: anthropic, openai, together, replicate, ollama (local, when reachable), openai_compatible (set OPENAI_COMPATIBLE_BASE_URL or pass base_url).
from_sessionNoId of a live collaboration or meeting (collab-…, meeting-…) or of any ended session in the archive, supplying participants and discussion.
include_selfNoDefault true: the target contributes to its own refinement. If false, supply at least one participant via with or from_session.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.0.0

TDQS

A4.5/5.0
Behavior5/5

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

Far beyond what the annotations convey: it discloses backup naming (<target>.bak-<timestamp>), atomic temp-file+rename replacement with mode preservation, concurrency locking with a fast-fail error, the conflict fallback to <target>.proposed-<timestamp>, fail-closed tool-list handling with a single retry, and exactly what data public sessions do and do not post. The annotations only say destructive/openWorld/non-idempotent; the description explains the practical consequences, including that public runs withhold system prompts and never include the target's recent activity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the purpose and the main workflow, which is good, but the body is a dense multi-hundred-word block with run-on sentences and near-duplicated rules (the skill-lookup precedence and the 'reuse, never overwrite' rule are restated, and 'next explains recovery' / 'warnings and next instructions' repeat). Most clauses are load-bearing for a destructive, open-world tool, which keeps this above a 2, but it would benefit from paragraphing or trimming.

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 12-parameter, destructive, open-world mutation tool with no output schema, the description covers the failure modes an agent must plan around: unparseable frontmatter, mid-run target changes, lock contention, tool-list rejection, skill-placement symlink restrictions, and public-session privacy limits. Nothing material about correct invocation appears to be missing.

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 baseline is 3, but the description adds real meaning beyond the schema: it explains what write:false actually does, how from_session ids are used to seed participants, the consequence of omitting 'tools' (target keeps inheriting everything, with a warning), and model-output limits (only name/description/model/tools/skills come from the model). Some parameters (rounds, focus, context, provider, base_url) are left entirely to their schema descriptions.

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+resource+scope: 'Refine an existing Claude Code agent in one call, preserving its identity and useful instructions.' The word 'existing' implicitly distinguishes it from creation siblings, and the rest of the text makes clear it is a multi-agent review-and-revise pipeline, not a simple edit.

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 states clear operating context: the target self-reviews by default, you add specialists via 'with' or inherit participants via 'from_session', and 'write: false previews without writes.' It also states a hard constraint (one improve run per target). It stops short of explicit 'do not use this when…' exclusions or a named alternative for creating new agents, so it is strong but not complete guidance.

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