Skip to main content
Glama

Add a Niche to Spaces

add_niche_spaces
Destructive

Add a niche to one or more Spaces to control who can see it; the update is all-or-nothing and can be undone.

Instructions

Use this to put a niche in one or more Spaces (ids from list_spaces). A Space controls who can see the niche, so adding or removing one changes access. Returns added and alreadyPresent. Undo with remove_niche_spaces. 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>",
      "spaceIds": "<spaceIds>"
    },
    "name": "add_niche_spaces"
  }
}

Input Schema

NameRequiredDescriptionDefault
nicheIdYesThe niche to change. Get one from `list_niches`.
spaceIdsYesThe ids of the Spaces to add the niche to, 1-100, unique. Get them from `list_spaces`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.20.1

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already flag a non-read-only, destructive, closed-world mutation, and the description adds substantial context beyond them: access-control side effects, all-or-nothing atomicity with the failure mode spelled out, a 403 refusal that must be reported rather than retried, idempotent repeats counted as `alreadyPresent`, and a 2-calls-per-minute per-niche limit.

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 purpose and then packed with operational facts (return values, undo path, permissions, atomicity, rate limit); every sentence carries information. It is dense rather than bloated, though the volume of clauses makes it read as a list of caveats rather than a tight statement.

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?

No output schema exists, yet the description documents the return fields (`added`, `alreadyPresent`) and the full failure shape (error lists offending ids). For a two-parameter mutation tool, an agent has everything needed to invoke it correctly and handle failures.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both params are documented in the schema, so the baseline is 3. The description adds only the provenance hint (ids from `list_spaces`) and the batching constraint already implied by the 1-100 item bound, so it does not materially extend the schema's meaning.

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 Spaces") and points at `list_spaces` for the ids. It is clearly distinguishable from the sibling `remove_niche_spaces`, which it names explicitly as the inverse.

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?

Gives explicit when-to-use (adding a niche to Spaces), names the alternative for undoing (`remove_niche_spaces`), states prerequisites (Manage access to the niche and to every Space), and tells the agent to batch all ids into one call due to the per-niche rate limit.

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