Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kanka-mcp list my campaigns"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for Kanka, the worldbuilding platform. Exposes a small set of tools that let any MCP-compatible agent (Claude Desktop, Claude Code, Cursor, custom clients) authenticate to a Kanka account and work with campaigns, entities, and search.
Status: Phase 4 — feature-complete. 15 tools, full CRUD over all 18 entity types, posts and relations sub-resources, OAuth 2.0 (Authorization Code + PKCE) with transparent refresh, and a client-side full-text search. Backed by a vitest test suite (43 tests across 7 files, including msw-mocked HTTP integration tests).
One command takes you from a fresh clone to a verified setup:
cd kanka-mcp
npm run quickstartThe script will:
Verify Node ≥ 20
npm install and build TypeScript
Ask whether you want to authenticate via Personal API token or OAuth 2.0
Prompt for the relevant credentials (input is hidden) and persist them with 0600 perms — token to ~/.config/kanka-mcp/token or OAuth client/secret to .env in the repo root
Run the end-to-end smoke test (and the OAuth browser flow if you chose option 2)
Optionally build and install the .mcpb extension — if Claude Desktop is detected, the script offers to build the bundle and open it directly so Claude Desktop's install dialog launches automatically. Because your credentials are already on disk, you can leave every field blank in the install dialog — the server resolves them from ~/.config/kanka-mcp/ at runtime.
Print ready-to-paste MCP-client config snippets as a manual fallback
Re-running npm run quickstart is safe — it'll detect existing credentials and offer to reuse them. Skip the rest of this README unless you want manual control.
Related MCP server: MCP-Kanka
Node.js 20 or newer
A Kanka account
A Kanka Personal API token (free tier allows 30 req/min; subscribers 90)
Sign in at https://app.kanka.io
Go to Settings → API: https://app.kanka.io/settings/api
Click Generate a new token and copy the value
Save it immediately — Kanka only shows the token once. If you lose it, you'll need to regenerate.
Tokens are valid for 365 days.
KANKA_TOKENThe server reads the token from the KANKA_TOKEN environment variable. Pick whichever method fits your workflow:
1. Inline for a single command — quickest way to run the smoke test once:
KANKA_TOKEN="paste-your-token-here" npm run smoke2. Export for the current shell session — persists for as long as the terminal is open:
export KANKA_TOKEN="paste-your-token-here"
npm run smoke
npm run smoke -- --mutate3. Persistent across shells — add it to your shell rc file (zsh shown; bash users use ~/.bashrc):
echo 'export KANKA_TOKEN="paste-your-token-here"' >> ~/.zshrc
source ~/.zshrc⚠️ Avoid this on shared machines — your token is sensitive.
4. Token file (no shell env at all) — drop the token into a 0600 file the server reads as a fallback:
mkdir -p ~/.config/kanka-mcp
printf '%s' 'paste-your-token-here' > ~/.config/kanka-mcp/token
chmod 600 ~/.config/kanka-mcp/tokenThe server checks KANKA_TOKEN first, then this file.
5. MCP client config — once you've verified the smoke test, supply the token directly to your client (Claude Desktop / Claude Code / etc.) so you never have to touch your shell. See Connect to an MCP client.
echo "$KANKA_TOKEN" | head -c 8 ; echo "…"Should print the first 8 characters of your token. If it prints … only, the variable isn't set in this shell.
From the repo root:
cd kanka-mcp
npm install
npm run buildThis compiles TypeScript to dist/.
The smoke script spawns the built server, performs the MCP handshake, and exercises the read-only path against the real Kanka API. It's the fastest way to confirm your token works end-to-end before configuring an agent.
KANKA_TOKEN="your-token-here" npm run smokeIt will:
List the tools the server exposes
Call kanka_auth_status
Call kanka_list_campaigns and print the first 5
Call kanka_get_campaign for the first one (or pass a campaign id as the second arg)
Call kanka_list_entities for character and print the first 5
Pass an explicit campaign id if you don't want the script to auto-pick:
KANKA_TOKEN="..." npm run smoke -- 12345--mutate mode (validates Phase 2 CRUD)Add --mutate to also exercise the create/update/get/delete cycle. The script creates a throwaway Note named kanka-mcp smoke test <ISO timestamp>, updates its entry, fetches it back by entity_id (which exercises the dual-ID resolver), and deletes it.
KANKA_TOKEN="..." npm run smoke -- --mutate
KANKA_TOKEN="..." npm run smoke -- 12345 --mutateThe Note appears in your campaign briefly. If the script crashes between create and delete, you may have to remove the Note manually.
Expected output (abridged):
→ initialize
kanka-mcp v0.1.0
→ tools/list
15 tools registered
→ kanka_auth_status
{ authenticated: true, source: 'env' }
→ kanka_list_campaigns
2 campaign(s):
- 12345: Legends of Tolria
- ...
→ kanka_get_campaign(12345)
name: Legends of Tolria
→ kanka_list_entities(12345, character)
N character(s); first 5: ...
✓ smoke test passed.mcpb extension (easiest)Claude Desktop has a native Extensions UI. The repo ships a bundle (.mcpb file) you can install in two clicks — no JSON editing, no PATH wiring.
The fastest path: run npm run quickstart. After the smoke test passes, the script offers to build the bundle and (on macOS) open it directly — Claude Desktop's install dialog launches automatically, and because your credentials are already saved at ~/.config/kanka-mcp/, you can leave every field in the dialog blank.
Manual flow:
Build the bundle: npm run pack:mcpb (produces kanka-mcp-<version>.mcpb in the repo root). Or download a pre-built release from https://github.com/torinvdb/kanka-mcp/releases/latest.
Double-click the .mcpb file — Claude Desktop is registered as the handler for the Desktop Extension UTI on macOS, so this launches the install dialog directly. (Equivalent: open kanka-mcp-0.1.0.mcpb.)
Or navigate manually: Claude Desktop → Settings → Extensions → Advanced settings → Install Extension… → select the file.
In the install dialog: paste your Kanka API token or leave it blank if you've already saved one at ~/.config/kanka-mcp/token (the server resolves it from disk as a fallback). OAuth fields are only needed if you registered an OAuth client.
Click Install — Kanka tools appear in your next conversation.
To upgrade later, repeat with the new .mcpb. Claude Desktop preserves your saved configuration across reinstalls of the same extension name.
claude mcp add kanka-mcp --env KANKA_TIER=subscriber \
-- node /absolute/path/to/kanka-mcp/dist/index.js(Token resolves automatically from ~/.config/kanka-mcp/token if you ran npm run quickstart.)
If you'd rather edit the config file directly — for example, if you use multiple Kanka accounts and want different config per workspace — edit Claude Desktop's claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"kanka-mcp": {
"command": "node",
"args": ["/absolute/path/to/kanka-mcp/dist/index.js"],
"env": { "KANKA_TOKEN": "your-token-here" }
}
}
}The file may not exist yet on a fresh Claude Desktop install — create it with the snippet above. Restart Claude Desktop to pick up the change.
The server speaks MCP over stdio. Any client that can launch a stdio MCP server will work — point it at node /absolute/path/to/kanka-mcp/dist/index.js with KANKA_TOKEN in the environment.
All configuration is via environment variables.
Variable | Required | Default | Purpose |
| one of token or OAuth | — | Personal API token (Bearer) |
| no | auto-detected |
|
| no | auto-tuned via | Hard override on the rate-limit bucket capacity. Setting this disables |
| no |
| Override the API base (for testing) |
| no |
| Override the OAuth host (for testing) |
| no |
| Fallback token location if |
| OAuth | — | OAuth app client id (register at app.kanka.io/settings/api-apps) |
| OAuth | — | OAuth app client secret |
| no | random ephemeral | Pin the loopback callback port (useful if your OAuth app's redirect URI is fixed) |
| no |
| Where access + refresh tokens are persisted |
| no |
| Per-request HTTP timeout; aborts the fetch and returns |
| no |
| Hard cap on response body size; oversized responses are rejected |
| no |
|
|
The server logs to stderr (stdout is reserved for MCP frames).
When making an API call, the server picks a token in this order:
Stored OAuth tokens (~/.config/kanka-mcp/oauth.json) — refreshed transparently on 401 or within 24h of expiry
KANKA_TOKEN environment variable
~/.config/kanka-mcp/token file
Most users only need a Personal API token. Use OAuth when you want a long-running login that can refresh itself, or when you're delegating access to a Kanka account that's not yours.
Register an app at https://app.kanka.io/settings/api?clients=1. Set the redirect URI to http://localhost:<port>/cb (Kanka's URL validator rejects 127.0.0.1 — use localhost). Pin a port via KANKA_OAUTH_REDIRECT_PORT and use the same port here.
After saving, Kanka issues you a Client ID (a numeric or UUID identifier) and a Client Secret. ⚠️ Do not confuse the Client ID with the app name you typed — they're different. Set the issued values:
export KANKA_OAUTH_CLIENT_ID="paste-issued-client-id" # number/UUID, NOT the app name
export KANKA_OAUTH_CLIENT_SECRET="paste-issued-secret"
export KANKA_OAUTH_REDIRECT_PORT=53117From your MCP client (or via npm run smoke -- --oauth), call kanka_oauth_login. The server opens your browser to Kanka's authorize page. After approval, tokens are persisted to KANKA_OAUTH_TOKEN_FILE (0600 perms) and used automatically.
Call kanka_auth_logout to clear the stored tokens.
Tokens are stored as a JSON file with restrictive permissions; we deliberately avoid native keyring dependencies for portability.
Auth & discovery
Tool | Purpose |
| Report whether a token is configured and where it was loaded from |
| Run the OAuth Authorization Code + PKCE flow; persists tokens locally |
| Clear stored OAuth tokens |
| Return the JSON Schema for an entity type's create/update payload |
Campaigns
Tool | Purpose |
| List campaigns the authenticated user has access to |
| Fetch metadata for one campaign by id |
Search
Tool | Purpose |
| Native Kanka name search — fast, but matches names only |
| Client-side full-text search across |
Entities (CRUD)
Tool | Purpose |
| Paginated list of entities, optionally filtered by type and arbitrary query filters |
| Fetch a single entity by type-scoped |
| Create an entity. |
| Partial PATCH on an existing entity |
| Permanently delete an entity. Requires |
Sub-resources — both follow a unified action: list | get | create | update | delete shape. They hang off the global entity_id, never the type-scoped id.
Tool | Purpose |
| List/read/create/update/delete posts (sub-notes) attached to an entity |
| List/read/create/update/delete typed links between entities (with attitude, two_way, etc.) |
Call kanka_describe_entity_type first whenever you're about to send a data payload — it returns the exact JSON Schema for that type, including which fields are required and any constraints. Some types have type-specific required fields beyond name:
calendar: requires weekday (array of at least 2 strings)
conversation: requires target_id (1 = users, 2 = characters)
dice_roll: requires parameters (e.g. "1d20+3")
kanka_list_entities accepts an optional since parameter (ISO 8601 timestamp) and returns a sync token in the response. To walk only what's changed:
// 1st call — full pull, save the returned token
{ "tool": "kanka_list_entities", "args": { "campaign_id": 113176, "entity_type": "character" } }
// → { "data": [...all 109 characters...], "sync": "2026-05-08T18:30:00.000Z" }
// 2nd call later — pass back the token to get only deltas
{ "tool": "kanka_list_entities", "args": {
"campaign_id": 113176, "entity_type": "character",
"since": "2026-05-08T18:30:00.000Z"
}}
// → { "data": [...only entities updated since...], "sync": "2026-05-08T19:42:11.000Z" }Backed by Kanka's native ?lastSync= query parameter — efficient for long-running agent workflows that don't want to refetch entire entity lists on every turn.
character, location, family, organisation, object, note, event, calendar, creature, race, quest, map, journal, ability, tag, conversation, dice_roll, timeline
MCP Client <—stdio JSON-RPC—> kanka-mcp (Node)
├─ Tool layer (15 tools)
├─ Service layer (id-resolver, full-text-search, html strip)
├─ Kanka HTTP client (token-bucket rate limiter, retry, error map)
└─ Auth (composite: OAuth → env token → file token)
│
└─ HTTPS → api.kanka.io/1.0 + app.kanka.io/oauth/*The Kanka API exposes every entity through both a type-scoped id (used by /characters/{id}) and a global entity_id (used by /entities/{id} and as the parent of posts/relations). The server resolves between the two transparently — pass whichever one you have.
Rate limiting is conservative: a token bucket sized to the configured tier with exponential backoff on 429. Adjust KANKA_RATE_LIMIT_PER_MIN if you have headroom.
Phase 1 ✓ — read-only path (auth, campaigns, search, list/get entities, describe schema)
Phase 2 ✓ — full CRUD (kanka_create_entity/update/delete), all 18 entity schemas, posts & relations
Phase 3 ✓ — OAuth 2.0 Authorization Code flow with PKCE + transparent refresh, file-based token persistence (0600 perms), kanka_full_text_search with HTML stripping
Phase 4 ✓ — vitest + msw test harness (43 tests), npm run check pipeline, ESLint guard against stdout pollution, TtlCache wired for the campaigns list
Bulk endpoints (Kanka has them for some types, but use cases are niche)
Image upload via URL fetch (Kanka uses multipart/form-data; v1 accepts pre-uploaded image UUIDs only)
Recorded fixtures from a real campaign for offline replay testing
npm run dev # tsx watch mode
npm run typecheck # tsc --noEmit
npm run lint # eslint (bans `console` to protect stdout / MCP framing)
npm run test # vitest run — unit + msw HTTP integration tests
npm run test:watch # vitest in watch mode
npm run check # typecheck + lint + test (run this before committing)
npm run build # compile to dist/
npm run smoke # end-to-end smoke against the live Kanka API
npm run smoke -- --mutate # additionally exercises CRUD
npm run smoke -- --oauth # exercises the OAuth flow
npm run validate:mcpb # validate manifest.json against the MCPB schema
npm run pack:mcpb # build kanka-mcp-<version>.mcpb for Claude DesktopPush a vX.Y.Z tag to trigger .github/workflows/release.yml. The workflow runs the full check pipeline, builds the .mcpb, and attaches it to a GitHub Release with install instructions. Users download from the Releases tab.
npm version patch # bumps package.json + creates a git tag
git push --follow-tagsTests live next to the code they cover (*.test.ts). The tsconfig.json excludes them from dist/, and eslint.config.js excludes them from the no-console rule so test files can log freely.
File | Coverage |
| Token bucket, burst window, penalty, refill wait |
| Status-code → |
| Cursor encode/decode, |
| msw-mocked HTTP: query encoding, 401 + refresh hook, 422 fields, 429 retry, 204 |
| HTML strip + snippet extraction |
| Cache hit/miss, |
| Required-field enforcement per type, |
Two GitHub Actions workflows live under .github/workflows/:
ci.yml — runs on every push/PRTypecheck, lint, full vitest suite, and build. No secrets needed; safe to run on fork PRs. Fails the merge if any step regresses.
integration.yml — live API smoke against your own campaignRuns npm run smoke against the real Kanka API. Triggers:
Manual (workflow_dispatch) from the Actions tab — optional mutate checkbox to additionally run the create/update/delete cycle, optional campaign_id to pin the test target
Weekly schedule (Mondays 08:00 UTC) — catches upstream Kanka API regressions
Requires one secret on the repository:
Setting | Where | Value |
| Settings → Secrets and variables → Actions → Secrets | Your Personal API token |
| Settings → Secrets and variables → Actions → Variables |
|
The workflow is gated to workflow_dispatch and schedule triggers only — it deliberately never runs on pull_request or push, so a fork PR can't ever trigger a run that would expose or consume your token. The --mutate job creates a throwaway Note named kanka-mcp smoke test <ISO timestamp> and deletes it; if a run crashes between create and delete, the leftover Note is named so you can find and remove it manually.
See SECURITY.md for the threat model and disclosure policy.
Hardening defaults baked into the server:
Request timeout (KANKA_REQUEST_TIMEOUT_MS, default 30 s) — every HTTP call to Kanka is wrapped in an AbortController; hangs surface as NETWORK_ERROR rather than blocking the agent indefinitely.
Response size cap (KANKA_MAX_RESPONSE_BYTES, default 10 MiB) — both the declared Content-Length and streamed bytes are checked; oversized responses are rejected before they OOM the process.
Rate limiter — token bucket with burst guard and exponential backoff on 429. On startup the server hits /profile, reads the API-reported rate_limit, and resizes the bucket automatically (30 rpm free / 90 rpm subscriber). KANKA_RATE_LIMIT_PER_MIN overrides and disables auto-tuning.
Token files — written with 0600 mode under ~/.config/kanka-mcp/ (created 0700).
OAuth — Authorization Code + PKCE (S256), 24-byte random state compared via crypto.timingSafeEqual, loopback callback bound to 127.0.0.1.
Log redaction — pino is configured to censor Authorization headers and any field named *token*, *secret*, etc., before writing to stderr.
Stdout pollution guard — ESLint bans console.* in src/ so a future contributor can't accidentally corrupt MCP framing.
CI audit — npm audit --omit=dev --audit-level=high runs on every push/PR; the workflow fails on high-severity advisories in production deps.
Run npm audit locally any time:
npm audit # all deps (may show low-severity dev-only items)
npm audit --omit=dev # production deps only — should always be 0Note:
npm audit(without flags) currently surfaces a few low-severity advisories from dev tooling (@anthropic-ai/mcpb→@inquirer/prompts→tmp). These are interactive-CLI components used only when packing the extension bundle locally; they never run at server runtime and aren't shipped in the.mcpb. Production deps remain at zero advisories — see CI for the authoritative gate.
MIT
Clear stored OAuth tokens (access + refresh). Personal API token configured via env or file is unaffected.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states what is cleared (OAuth tokens) and what is not (API token), which is sufficient for a logout operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the key action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple logout action with no output schema, the description provides enough context. It could mention the expected response, but it's not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description adds no parameter-specific info, but the baseline for 0 parameters is 4, and the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Clear' and the resource 'stored OAuth tokens (access + refresh)'. It is specific and distinguishes from sibling tools like kanka_oauth_login.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies that personal API tokens are unaffected, providing context. However, it does not explicitly state when to use this tool over alternatives, though it is implicit for logout scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the server has a usable Kanka credential and where it came from (env var, token file, OAuth, or none). Call this first if other tools return AUTH_REQUIRED — it'll tell you what's missing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It clearly describes a read-only check of credential status without side effects. However, it doesn't explicitly state that it does not modify any state, which would be helpful but is not critical given the context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, highly concise, with the key purpose and usage guidance front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description explains what the tool returns (credential source and availability). This is sufficient for a simple status check tool, and all necessary context is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter documentation is needed. Baseline for 0 parameters is 4, but the description is perfect for this case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks for a usable Kanka credential and identifies its source (env var, token file, OAuth, or none). This specific verb+resource distinguishes it from sibling tools like kanka_auth_logout or kanka_oauth_login.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Call this first if other tools return AUTH_REQUIRED — it'll tell you what's missing.' This tells the agent when to use it and implies it's a diagnostic step before other auth-dependent tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new entity. Call kanka_describe_entity_type first to discover the per-type schema for data. Returns the created record including its type-scoped id and global entity_id.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| entity_type | Yes | ||
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses return format including two IDs and hints at dynamic schema for `data`. Lacks explicit authorization or error behavior, but sufficient for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core purpose, no redundant words. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested object, many entity types, no output schema), the description provides a complete workflow: create, prerequisite, and return info. Directing to describe_entity_type fills the gap for data schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains `data` is type-dependent and directs to describe_entity_type, but does not describe `campaign_id` or `entity_type` beyond schema enum. Adds moderate value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a new entity', a specific verb and resource. Distinguishes from siblings like update/delete/list. Provides prerequisite hint and return value description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call kanka_describe_entity_type first to discover the per-type schema for `data`, which is a crucial usage guideline for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete an entity. Requires confirm: true to execute. Note: kanka_get_entity by entity_id may continue to succeed briefly via cache; pass an unknown entity_id to bust the resolver if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| entity_type | Yes | ||
| id | Yes | ||
| confirm | Yes | ||
| entity_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It indicates the operation is permanent and requires confirmation, and it warns about caching effects. This is clear behavioral information, though it does not discuss reversibility or side effects on related data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the purpose and key requirement. Every sentence adds value, with no wasted words. It is perfectly sized for a straightforward tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary behavior and a caching caveat, but given the lack of output schema and annotations, it does not explain the return value or error scenarios. For a delete tool, knowing what to expect in response would enhance completeness. Without that, it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It only explains the `confirm` parameter (must be true) and hints at `entity_id` for cache busting. The other parameters (`campaign_id`, `entity_type`, `id`) are not described, leaving significant gaps for a tool with 5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes an entity permanently. It uses the specific verb 'delete' and resource 'entity', and the title 'Delete entity' reinforces this. It is distinct from siblings like kanka_create_entity, kanka_update_entity, and kanka_get_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires `confirm: true` to execute, providing a key usage condition. It also gives a note about cache behavior for `entity_id`. However, it does not explicitly state when to use this tool versus alternatives, though the purpose implies its use for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the JSON Schema for the create/update payload of a Kanka entity type. Call this before kanka_create_entity or kanka_update_entity to discover required and optional fields.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool returns a JSON Schema, which is a read-only behavior. It does not mention side effects, authentication, or rate limits, but for a simple schema retrieval, this is sufficient and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first sentence states the core purpose, and the second provides usage guidance. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema). The description fully explains its purpose and relationship to sibling tools, making it complete for an AI agent to understand when and why to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'entity_type', has an enum in the schema. The description does not explicitly describe the parameter, but it adds meaning by linking it to the purpose of retrieving the schema for that entity type. Given the enum is self-explanatory and the description provides context, it adds sufficient semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a JSON Schema for the create/update payload of a Kanka entity type. It explicitly names the target resources (kanka_create_entity, kanka_update_entity) and their relationship, distinguishing from sibling tools by specifying it should be called before them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('before kanka_create_entity or kanka_update_entity to discover required and optional fields'). It implies when not to use it (after creating/updating, or for other operations not needing schema discovery). It provides clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across the body text (entry HTML) of entities by paginating typed list endpoints, stripping HTML, and matching locally. Costs API budget — narrow types and lower max_pages_per_type to keep it cheap. Returns matches with a snippet around the hit.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| query | Yes | ||
| types | No | ||
| max_pages_per_type | No | ||
| per_page | No | ||
| limit | No | ||
| case_sensitive | No | ||
| regex | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It discloses that the tool paginates, strips HTML, matches locally, and returns snippets. It also mentions API budget consumption. It does not detail performance implications or potential failure modes, but covers the key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the purpose and mechanism, then cost advice. No wasted words, each sentence adds value. Ideal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core search mechanism and cost, but omits details on parameter usage for 6 of 8 parameters. No output schema, so return format is barely mentioned ('snippet'). More guidance on parameter semantics would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only adds guidance for 'types' and 'max_pages_per_type'. Other parameters like 'query', 'campaign_id', 'per_page', 'limit', 'case_sensitive', and 'regex' are left unexplained. The description adds limited value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the action 'search' and the resource 'body text of entities', and explains the method (paginating, stripping HTML, matching locally). It distinguishes from sibling tools like kanka_search, which likely does a different kind of search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'Costs API budget — narrow types and lower max_pages_per_type to keep it cheap.' It warns about cost and suggests parameter tuning. It does not explicitly state when not to use, but the cost implication implies alternatives might be preferred for small searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch metadata for a single campaign by id.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states 'fetch metadata' implying read-only, but does not disclose any other behavioral traits (e.g., error behavior, response format, restrictions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 8 words, front-loaded with action and resource. No wasted words, but at the cost of omitting useful context. Appropriate for a simple tool but slightly too terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description fails to explain what 'metadata' includes or what the return value looks like, leaving the agent with incomplete information for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description mentions 'by id' linking to the parameter, but does not add meaning beyond the schema's explicit 'campaign_id' field. Schema already defines integer with exclusiveMinimum:0.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'fetch' and resource 'metadata for a single campaign by id', clearly distinguishing from sibling 'kanka_list_campaigns' which lists all campaigns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance, but the purpose and naming imply use when a single campaign ID is known. The presence of a sibling list tool provides implicit differentiation. Lacks when-not or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single entity by either its type-scoped id (requires entity_type) OR its global entity_id. The dual-ID system is resolved transparently: if you only know entity_id, the resolver will discover the type and fetch the typed record.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| entity_type | No | ||
| id | No | ||
| entity_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions transparent ID resolution but does not disclose if this involves extra API calls, side effects, authentication requirements, or rate limits. It fails to fully inform the agent of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each serving a purpose: the first states the action, the second explains the ID resolution. No unnecessary words, well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should cover return format, error handling, or limits for a fetch tool. It lacks these details, making it incomplete for robust usage by an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds meaning by explaining the dual-ID system and the relationship between entity_type, id, and entity_id. However, it does not describe campaign_id, which is required, leaving a gap in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a single entity', giving a specific verb and resource. It distinguishes from sibling tools like kanka_list_entities by focusing on fetching one entity. The mention of two ID systems adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two ways to specify the entity (type-scoped id vs global entity_id), giving usage context. However, it does not explicitly say when to use this tool over alternatives like kanka_search or kanka_list_entities, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover which Kanka campaigns the authenticated user can access. Call this first to find the campaign_id you need for entity-level operations. Results are cached for 60 seconds — call again if you suspect campaigns were just created/removed in the Kanka UI.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature and 60-second caching, which are key behavioral traits. However, without annotations, it does not mention authentication requirements (though 'authenticated user' is stated) or pagination behavior beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently cover purpose, usage, and caching. No extraneous text; front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers purpose, usage context, and caching. The missing documentation of the 'page' parameter is a minor gap given its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'page' parameter at all, despite 0% schema description coverage. The agent receives no guidance on how pagination works or how to use this optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool discovers accessible Kanka campaigns and provides the campaign_id for subsequent operations, distinguishing it from siblings like kanka_get_campaign and kanka_list_entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises calling this first to obtain campaign_id for entity-level operations and notes caching behavior (60 seconds) with a hint to recall if campaigns may have changed, providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse a campaign's entities. Use this to enumerate, page through, or filter by type / name / tags. For looking up a specific entity by id, prefer kanka_get_entity. For text-content search, use kanka_full_text_search.
Incremental sync: pass since (ISO 8601, e.g. the previous response's sync value) to receive only entities modified after that time. The response includes a sync token to use on the next call.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| entity_type | No | ||
| page | No | ||
| per_page | No | ||
| filters | No | ||
| since | No | ISO 8601 timestamp (e.g. 2026-05-08T18:00:00Z). Returns only entities updated after this time. Use the `sync` token from a previous response to walk the delta. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must convey behavior. It accurately implies read-only operation via 'browse' and 'list', and reveals the incremental sync mechanism. It does not explicitly mention authentication needs or rate limits, but these are common and not required for scoring high transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs with front-loaded purpose and sibling alternatives, followed by a dedicated explanation of incremental sync. No redundant sentences; every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers browsing, filtering, and sync, but lacks details on the response structure (e.g., entity object format, pagination metadata) since there is no output schema. This is a gap for a tool with nested parameters and sync tokens.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (17%), but the description adds meaning by specifying filtering by type/name/tags and explaining the 'since' parameter for incremental sync. It does not elaborate on basic pagination parameters (page, per_page), but those are self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool browses campaign entities with enumeration, paging, and filtering by type/name/tags. It distinguishes itself from siblings by directing users to kanka_get_entity for specific IDs and kanka_full_text_search for text search, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use this tool versus alternatives (kanka_get_entity for ID lookup, kanka_full_text_search for text search). Also provides clear guidance on incremental sync usage with 'since' parameter and 'sync' token.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the OAuth 2.0 Authorization Code flow with PKCE. Opens a browser to the Kanka authorize page; on approval, persists access + refresh tokens to disk so subsequent tool calls authenticate transparently. Requires an OAuth app registered at https://app.kanka.io/settings/api?clients=1. Provide client_id/client_secret here or via KANKA_OAUTH_CLIENT_ID / KANKA_OAUTH_CLIENT_SECRET env vars.
| Name | Required | Description | Default |
|---|---|---|---|
| client_id | No | ||
| client_secret | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully bears the transparency burden. It discloses side effects (opens browser, persists tokens to disk) and prerequisites (OAuth app registration, env var fallback). This is adequate for a login tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, each contributing essential information: purpose, flow, persistence, and prerequisites. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of OAuth flows and absence of output schema/annotations, the description covers purpose, flow, persistence, and prerequisites. It lacks details on error handling or redirect URIs, but is sufficient for a login tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds meaning by explaining that client_id and client_secret can be provided directly or via environment variables. However, it does not specify formats, constraints, or defaults, so value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as running the OAuth 2.0 Authorization Code flow with PKCE, specifying the action (run, opens, persists) and resource (Kanka authorize page, tokens). It distinguishes from siblings like kanka_auth_logout and kanka_auth_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (to authenticate for subsequent calls) and prerequisite requirements (registered OAuth app, env vars). It does not explicitly state when not to use it or list alternative tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List, read, create, update, or delete the posts (sub-notes) attached to an entity. Posts hang off the GLOBAL entity_id, not the type-scoped id. Provide action plus the relevant fields: list (page), get (id), create (data), update (id, data), delete (id, confirm: true).
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| entity_id | Yes | The GLOBAL entity_id (not the type-scoped id) | |
| action | Yes | ||
| id | No | ||
| data | No | ||
| confirm | No | ||
| page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavioral traits. It mentions the delete action requires confirm: true, implying destructiveness, but does not elaborate on other side effects (e.g., irreversible changes, permissions). The global entity_id detail is helpful, but more context on mutation behaviors would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states purpose, the second provides usage guidance. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, nested objects, no output schema), the description covers actions, required fields, and the global entity_id nuance. It omits return value details and pagination behavior for list, but the action-field mappings are adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (14%), so the description compensates by explaining the action parameter and mapping each action to required fields (e.g., create needs data). It also reinforces the global entity_id usage. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs CRUD operations on posts (sub-notes) attached to an entity, specifying the verb and resource. It distinguishes from sibling entity tools by focusing on posts and the global entity_id concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists the actions and required fields for each operation (e.g., list requires page, delete requires id and confirm), providing clear usage guidance. It does not explicitly state when not to use or compare to siblings, but the specificity is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List, read, create, update, or delete relations between entities. Relations hang off the GLOBAL entity_id of the source. The target_id in data is the global entity_id of the destination. Set two_way: true to create reciprocal relations.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| entity_id | Yes | The GLOBAL entity_id (not the type-scoped id) | |
| action | Yes | ||
| id | No | ||
| data | No | ||
| confirm | No | ||
| page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It explains the key trait that relations use global entity_ids and the two_way option. However, it does not disclose side effects of delete/update, authentication requirements, or pagination behavior. For a CRUD tool with 7 parameters, more behavioral context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four short sentences, each adding necessary information. There is no redundancy or filler. It efficiently conveys the tool's purpose, key concepts, and an optional feature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, nested data object, no output schema, no annotations), the description provides essential information but leaves gaps. It does not explain the structure of data beyond target_id and two_way, pagination with page, or error scenarios. More complete context would help an agent invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14%, so the description must compensate. It adds meaning for entity_id (global entity_id), and explains that data contains target_id and two_way. This significantly clarifies the data object. However, confirm and page parameters remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the CRUD operations on 'relations between entities', specifying the resource and actions. It distinguishes from sibling tools that deal with entities themselves, and adds detail about the use of global entity_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that relations are based on the source's global entity_id and that target_id in data is the destination's global entity_id. It also mentions the two_way option for reciprocal relations. However, it does not explicitly state when to use this tool versus alternatives, though no direct alternative exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find entities by NAME within a campaign — fast, server-side, but matches names only (no entry/body text). Prefer this when you know the entity name. For matching against entry text, use kanka_full_text_search instead. For listing/browsing, use kanka_list_entities.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| query | Yes | ||
| types | No | ||
| page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'fast, server-side' and scoping to names, but does not cover pagination, rate limits, or auth requirements. The description adds some value but lacks essential behavioral context beyond what is implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a purpose: defining scope, noting performance, and providing usage alternatives. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and 4 parameters with 0% schema description coverage, the description is too sparse. It omits details about pagination, optional filters, return format, and error cases, leaving the agent underinformed for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only implicitly refers to campaign_id and query via 'by NAME within a campaign'. Parameters 'types' and 'page' are not mentioned at all, nor their purposes or constraints. The description fails to add meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches entities by name within a campaign, distinguishing it from full-text search and listing tools. It specifies 'matches names only (no entry/body text)', which is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Prefer this when you know the entity name' and alternatives are named (kanka_full_text_search for body text, kanka_list_entities for browsing). This directly helps the agent decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partial update (PATCH) on an existing entity. Provide only the fields you want to change. The id is the type-scoped id (e.g. character id), not entity_id.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | ||
| entity_type | Yes | ||
| id | Yes | ||
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it is a PATCH (partial update) and clarifies id semantics. No annotations provided, so description carries full burden. Lacks details on permissions or error states but sufficient for a simple update.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Front-loaded with action and purpose. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description covers essential aspects: partial update, field selection, id type. Could mention response format, but not critical for a well-known operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, description adds value for 'id' (type-scoped) and 'data' (partial update). Does not describe campaign_id or entity_type, but enum for entity_type is in schema. Compensates partially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Partial update (PATCH) on an existing entity'. Verb 'update' and resource 'entity' are specific. Distinguishes from sibling tools like create_entity and delete_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instruction: 'Provide only the fields you want to change.' Clarifies id is type-scoped, not entity_id. However, no explicit when-not-to-use or alternative mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0kanka_auth_logoutkanka_auth_statuskanka_create_entitykanka_delete_entitykanka_describe_entity_typekanka_full_text_searchkanka_get_campaignkanka_get_entitykanka_list_campaignskanka_list_entitieskanka_oauth_loginkanka_postskanka_relationskanka_searchkanka_update_entityScored across 15 tools
Most tools have clearly distinct purposes (e.g., create vs. update vs. delete, search vs. full text search vs. list). However, kanka_search and kanka_full_text_search could be confused if descriptions are overlooked, and kanka_list_entities overlaps slightly with browse/search capabilities.
Tools generally follow a 'kanka_verb_noun' pattern, but 'kanka_posts' and 'kanka_relations' are nouns only, breaking consistency. The use of 'full_text_search' with underscores is fine, but the mix of verbs and bare nouns is noticeable.
With 15 tools, the server covers authentication, campaign management, entity CRUD, posts, relations, search, and schema discovery without feeling bloated. Each tool addresses a distinct need, and the count is appropriate for the domain.
The tool surface covers essential CRUD for entities, posts, and relations, plus search and auth. Minor gaps: there is no tool to list entity types or manage campaigns beyond fetching metadata, but these are not critical for typical workflows.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Agent knowledge, private memory and coordination. Connect with MCP OAuth or an agent key.
Rick and Morty MCP — wraps the Rick and Morty API (free, no auth)
Manage your tabletop RPG campaign from any MCP client: worlds, sessions, quests, lore, recaps.
