Skip to main content
Glama

Add Labels to a Niche

add_niche_labels
Destructive

Adds a niche to one or more labels in a single all-or-nothing call. Returns added and already-present counts so users can confirm changes, and supports undo via label removal.

Instructions

Use this to put a niche in one or more labels (ids from list_labels). Returns added and alreadyPresent. Undo with remove_niche_labels. The same rights as the web app: the user needs Manage access to the niche, and to every Space added or removed. A refusal is a 403, so tell the user instead of retrying. A change is all or nothing: if any id is unknown, or a Space is one the user has only view rights on, the whole call fails and nothing changes (the error lists the offending ids). Ids already in the wanted state are counted, never errors, so a repeat is safe. Costs nothing. Limited to 2 calls per minute per niche, so put every id in one call.

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": {
      "nicheId": "<nicheId>",
      "labelIds": "<labelIds>"
    },
    "name": "add_niche_labels"
  }
}

Input Schema

NameRequiredDescriptionDefault
nicheIdYesThe niche to change. Get one from `list_niches`.
labelIdsYesThe ids of the labels to add the niche to, 1-100, unique. Get them from `list_labels`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.20.1

TDQS

A4.9/5.0
Behavior5/5

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

Goes well beyond the annotations (which only flag a non-read-only, destructive write) by disclosing permission requirements (Manage access on the niche and every Space), atomic all-or-nothing semantics, idempotency of repeat ids, the 403 refusal path, and a 2-calls-per-minute-per-niche rate limit. It also names the return fields `added` and `alreadyPresent`.

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

Conciseness5/5

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

Purpose is front-loaded in the first clause, followed by return values, inverse operation, permissions, failure semantics, idempotency, cost, and rate limit. Every sentence carries distinct operational information with no filler.

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?

Although there is no output schema, the description names the returned fields, and for a 2-parameter mutation tool it covers permissions, atomicity, error handling, idempotency, throttling, and cost. Nothing an agent needs to call it correctly is 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% and both parameters are already documented with sourcing hints, so the baseline would be 3. The description adds practical meaning by framing `labelIds` as a batch to be submitted together in a single call rather than split, which is behavioral usage guidance the schema 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 and resource ('put a niche in one or more labels') and immediately names the inverse sibling, `remove_niche_labels`, so an agent can distinguish write-add from write-remove 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 Guidelines5/5

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

Explicitly names the alternative for undo, tells the agent to source ids from `list_labels`, and instructs batching 'put every id in one call' due to the rate limit. It also gives an exclusion rule: on a 403, tell the user instead of retrying.

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