Skip to main content
Glama
Sign In

SHIP

by ai.letsship
OverviewDiscussionsAdmin

Set a per-issue agents-override for one role

set_agents_override
DestructiveIdempotent

Patch one role's harness/model/effort/prompt for a single mission, layered over ship.yml per-field (a role or field this call omits keeps resolving from ship.yml — SHIP-337). Use promptContent or promptPath(+promptRef) to run an ephemeral prompt experiment (spec D9) without committing to the target repo. Read-modify-write: this call is merged onto the previously stored override record (via get_agents_override), so a prior set for a DIFFERENT role — or a different field on this same role, e.g. an earlier harness pin — survives; the underlying PUT is a full-record replace and would otherwise silently drop it. This tool calls the SHIP API, documented at https://letsship.ai/docs/api.

Input Schema

NameRequiredDescriptionDefault
roleYesThe role this override entry patches
sizeNoContainer size for this role on this mission
modelNoThe model id this role uses for this mission. The harness must support it
effortNoReasoning effort for this role, mapped to the harness's own control at dispatch: low, medium, high or xhigh, and also max on claude-code. A value the harness does not take is refused at dispatch.
harnessNoThe code harness this role runs on for this mission
issueIdYesThe mission's issue id: a Linear key or a GitHub Issues id, e.g. SHIP-353 or WEB-42
sandboxNoSandbox name or id this role starts in for this mission (beats ship.yml and the project default)
rejectOnNoReview rejection threshold — only meaningful on the reviewer role
projectIdYesProject id the mission belongs to
promptRefNoGit ref for promptPath — only meaningful alongside promptPath.
baseBranchNoOverride the pipeline's fork/target branch for this mission
checkpointNoPause the pipeline after this role's stage completes
promptModeNoHow this prompt relates to the repo's own .ship/agents/<role>.md (or ship.yml-pointed) layer. replace (default) makes this the role's only role-prompt layer; extend resolves the repo's layer first and appends this content after it, as a separately attributed span. Only meaningful with promptContent or promptPath. NOTE: the merge is per FIELD, and prompt is one field — a later call that sets a new promptContent/promptPath without repeating promptMode replaces the whole stored prompt, reverting to replace.
promptPathNoRepo-relative path to an L2 prompt file. Without promptRef this is the SHIP-347 pointer form (resolved at the pinned base branch); with promptRef it's a path+ref experiment resolved at that ref.
promptContentNoInline prompt-experiment body, capped at 30,000 characters. Mutually exclusive with promptPath.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / effort / description
      Added value: +"Reasoning effort for this role, mapped to the harness's own control at dispatch: low, medium, high or xhigh, and also max on claude-code. A value the harness does not take is refused at dispatch."
    • addedInput schema / properties / harness / description
      Added value: +"The code harness this role runs on for this mission"
    • addedInput schema / properties / model / description
      Added value: +"The model id this role uses for this mission. The harness must support it"
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Goes well beyond the annotations (destructiveHint, idempotentHint, readOnlyHint) by disclosing the read-modify-write contract: the call is merged onto the previously stored record, a prior set for a different role or a different field survives, and the underlying PUT is a full-record replace that would otherwise silently drop it. It also notes a value the harness does not accept is refused at dispatch — exactly the behavioral risk an agent needs before calling.

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 core action and the merge semantics before the API link, and every sentence carries real information. It is dense with parentheticals (SHIP-337, spec D9, 'e.g. an earlier harness pin') that add traceability but slightly slow parsing of an already long description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 15 parameters, no output schema, and a destructive+idempotent annotation profile, the description supplies the missing merge/replace semantics an agent must know to avoid silent data loss. The remaining gap is sibling routing: it names get_agents_override but omits clear_agents_override, the counterpart for removal.

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 description coverage is 100%, so the baseline is 3, but the description adds field-level meaning beyond the schema: promptContent/promptPath are framed as an ephemeral experiment path and the merge is described as per-FIELD, which clarifies why an omitted parameter persists rather than reverting. The destructive/merge semantics of omitting a parameter are the key added value the schema's per-property text does not convey.

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+resource ('Patch one role's harness/model/effort/prompt for a single mission') and scopes it to a single role on a single mission. It also distinguishes itself from the read path by naming get_agents_override, so an agent can pick between read and write without opening either 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?

Gives clear conditions for the prompt-experiment path (promptContent or promptPath(+promptRef) to run an ephemeral experiment) and explains the layering-over-ship.yml model, plus points to get_agents_override for reads. It never mentions clear_agents_override, the sibling an agent would need to remove an override, so the when-not side is incomplete.

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

All SHIP toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources