Skip to main content
Glama

Add a kit piece

add_kit_piece

An outfit, place or prop from an image, a link or a stock photo, cropped The kit is what a music video is made from besides the artist’s character: outfits, places and props. Each is in one artist’s kit (owner_artist_id, a project in a Creator workspace; an outfit’s is its artist_id) and serves their songs; shared true offers it to every other artist’s songs too (owner_name says whose it is). Each has a name and an @handle unique in the workspace; a music video brief (direction) that mentions @handle uses that piece exactly as it is, and the director designs the rest. An outfit needs artist_id (its artist's kit); a place or prop goes in owner_artist_id's kit (left out: the workspace's only artist, else its first, shared). shared true offers it to every other artist's songs too (default false). The image is an upload or file_url (JPEG, PNG or WebP, at least 512 px on its short side, up to 15 MB, with rights_confirmed) or a stock_id from search_stock (credited, no rights needed). crop keeps a rectangle of it (fractions; at least 256 px on its short side), for a prop cut out of a bigger photo. handle follows the name (Blue set → blue-set; -2 when taken) unless given. Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

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": {
      "kind": "<kind>",
      "name": "<name>"
    },
    "name": "add_kit_piece"
  }
}

Input Schema

NameRequiredDescriptionDefault
cropNoThe rectangle to keep, in fractions of the image: {"x","y","w","h"}; the whole image when omitted
kindYesoutfit (an artist’s), place or prop
nameYesWhat it is called, e.g. Blue set
handleNoIts @handle (default: from the name)
sharedNoOffer it to every other artist’s songs too (default false)
file_urlNoA public https URL of the image (a file on your computer: create_upload's file_url, or upload it with the CLI)
stock_idNoA stock photo id from search_stock instead of an image
artist_idNoThe artist an outfit belongs to (outfits only)
descriptionNoWhat it is, for the director (a stock photo’s caption by default)
owner_artist_idNoA place or prop: the artist whose kit it goes in (a project in a Creator workspace)
rights_confirmedNoYou have the rights to use the image (needed for an upload or file_url)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / file_url / description
      Previous value: -"A public https URL of the image (or upload a file with the CLI)"New value: +"A public https URL of the image (a file on your computer: create_upload's file_url, or upload it with the CLI)"
  2. Changed3 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"outfit (an artist’s), place or prop (the workspace’s)"New value: +"outfit (an artist’s), place or prop"
    • addedInput schema / properties / owner_artist_id
      Added value: +{
      +  "description": "A place or prop: the artist whose kit it goes in (a project in a Creator workspace)",
      +  "maxLength": 120,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / shared
      Added value: +{
      +  "description": "Offer it to every other artist’s songs too (default false)",
      +  "type": "boolean"
      +}
  3. Added

TDQS

A4.1/5.0
Behavior5/5

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

Beyond the annotations it discloses failure modes with exact codes (402 plan_required, 402 storage_full), the prerequisite of an active plan and available storage with the get_account fields to check, the rights_confirmed requirement for uploads/URLs, and the deterministic handle behavior ('Blue set' → blue-set, with -2 suffix when taken). It also explains the blast radius of shared=true, which is the key side effect an agent must reason about.

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?

Content is valuable but the structure is weak: the first sentence is a truncated fragment, and the shared semantics ('shared true offers it to every other artist's songs too, default false') are stated twice in near-identical wording. It is dense rather than front-loaded, so an agent must read the whole block to find the required-parameter rules.

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?

For an 11-parameter mutation with a nested crop object and no output schema, it covers ownership, sharing, image constraints, plan and storage gating thoroughly. The notable gap is that nothing says what the call returns (the created piece, its id, its resolved handle), which matters precisely because there is no output schema to fall back on.

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 schema coverage at 100% the baseline is 3, but the description genuinely adds meaning: it explains crop's rationale (cutting a prop out of a larger photo, minimum 256 px on the short side), how handle is auto-derived from name, that description defaults to a stock photo's caption, and the owner_artist_id fallback chain. The awkward first clause about sources is the only place where prose is less informative than the schema.

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?

The definition states a specific verb (add) and resource (a kit piece: outfit, place or prop) and defines what a kit is, so an agent knows exactly what gets created. The opening fragment ('...cropped The kit is what a music video is made from') is garbled and delays the point, and it never contrasts this with update_kit_piece or delete_kit_piece by name.

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 gives concrete selection rules among the input paths: an outfit needs artist_id, a place or prop goes in owner_artist_id (with an explicit fallback to the workspace's only artist, else its first, when omitted), and image source is an upload/file_url versus a stock_id from search_stock. What's missing is explicit routing to sibling operations, e.g. that changing an existing piece is update_kit_piece and inspecting it is get_kit_piece.

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