Click on "Install 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., "@Jama MCP Server search requirements about volume sync"
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 production-grade Model Context Protocol (MCP) server for the Jama requirements management system, combining high-precision RAG retrieval with native REST API filtering. An LLM client (Claude Desktop, etc.) can autonomously choose between semantic search and structured metadata queries.
┌──────────────────────── MCP (stdio) ────────────────────────┐
│ │
LLM ──────┤ init_jama_project get_sync_progress │
Client │ search_jama_semantics query_jama_native_metadata │
│ │
│ server.py (FastMCP + APScheduler + thread pool) │
│ │ │
│ ├── rag_pipeline.py (Multi-Query + Hybrid + RRF + │
│ │ cross-encoder reranker) │
│ ├── jama_client.py (OAuth2 + pagination + HTML clean)│
│ └── db_setup.py (SQLite + FTS5 + sqlite-vec) │
│ │
└──────────────────────────────────────────────────────────────┘
│ │
Jama REST API Local CPU embeddings (default:
(read-only GET) bge-small-en-v1.5) + Azure OpenAI
(optional, text-embedding-3-small)Related MCP server: AXYS MCP Lite
search_jama_semantics)Multi-Query — the query is expanded into 3-5 sub-queries. The MCP LLM
client performs the expansion and passes the variants via the
sub_queries parameter; when none are supplied, the server falls back to
deterministic lexical variants (stopword-stripped + truncated) so RRF
fusion still benefits from multiple recall angles. No server-side chat
LLM is configured or called.
Hybrid recall — for each sub-query: vector recall (sqlite-vec, cosine)
keyword recall (FTS5, BM25), each capped at candidate_k.
RRF fusion — Reciprocal Rank Fusion merges all ranked lists into one
candidate pool of ≤ candidate_k unique chunks.
Rerank — a local cross-encoder (cross-encoder/ms-marco-MiniLM-L-6-v2,
~80MB, CPU, ONNX via fastembed/onnxruntime) scores (query, chunk) pairs via
a sequence-classification head; top top_k returned. It runs on the SAME
onnxruntime as the bge embedding model — no torch/transformers dependency,
so the Windows c10.dll/WinError 1114 load failure is eliminated. If the
model is unavailable, the pipeline gracefully falls back to RRF scores.
Model weights are fetched from the HuggingFace China mirror
(HF_ENDPOINT=https://hf-mirror.com) on first use, then served from cache.
The server is designed to survive crashes without losing data and to come back up consistent on restart:
Atomic per-item indexing — each item's chunks (text + FTS5 + sqlite-vec)
are replaced in a single write_txn (BEGIN IMMEDIATE), so a crash mid-sync
never leaves a half-written item. done/progress only advance after the
commit, so the DB is consistent up to the last flushed batch.
Idempotent re-sync — upserts overwrite (never duplicate), so re-processing already-indexed items on resume is harmless.
Startup recovery — _resume_interrupted_syncs re-queues any project left
INITIALIZING by a prior crash, so the server self-heals without manual
action.
Concurrency guard — init_jama_project refuses a duplicate concurrent
sync for a project that already has a job in flight, returning the existing
job_id instead of spawning a racing second worker.
Bounded HTTP retries — 429 rate-limit handling is a bounded loop (not
recursion), so a persistent rate-limit fails cleanly instead of overflowing
the stack; Retry-After parsing tolerates non-numeric values; a 401 mid-sync
refreshes the token and retries the page; malformed JSON bodies are retried.
WAL mode + write lock — SQLite runs in WAL with a process-wide write
lock, so the scheduler's writer and MCP reader threads coexist without
SQLITE_BUSY failures.
Jama rich-text (Description / Test Case Steps) is cleaned to plain text with
BeautifulSoup before being wrapped in LlamaIndex Document objects. The
documents are split into TextNode chunks by LlamaIndex's SentenceSplitter
(recursive, sentence-aware; chunk_size=512, chunk_overlap=80 to preserve
context for the ~30% long-form items). The item name is prepended to each chunk
so the title is always retrievable.
query_jama_native_metadata)Bypasses the vector store for exact-match questions (specific document key,
status, item type). Uses /abstractitems which honours itemType,
contains and documentKey server-side; status is refined client-side.
Handles pagination internally, returns up to 20 core metadata records.
On startup, APScheduler registers a job (every 2h by default) that reads the
projects table for projects in READY status (INITIALIZING is deliberately
excluded — those are handled by crash recovery) along with their
last_sync_time, then walks Jama items whose modifiedDate > last_sync_time,
re-cleans/re-chunks them and updates the FTS5 + sqlite-vec indexes. New items
are added; modified items have their old chunks replaced atomically. A project
that already has an in-flight job is skipped so a scheduled sync never races a
user-initiated one.
# Direct (if GitHub is reachable)
git clone https://github.com/yyy188/jama-mcp-server.git jama
cd jama
# China mirror (if github.com is slow/blocked)
git clone https://gh-proxy.com/https://github.com/yyy188/jama-mcp-server.git jama
cd jamauv (deterministic, reproducible)uv is a single-binary Python package manager
(~20 MB). Its lockfile (uv.lock) pins the entire dependency tree — every
package and its transitive deps — so uv sync on a new machine produces the
exact same environment, with no version-resolution surprises.
# 1. Install uv (one-time, ~20 MB single binary)
# Windows: winget install astral-sh.uv
# macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
# (or: pip install uv)
# 2. Sync dependencies from the lockfile (creates .venv, installs 116 packages)
uv sync
# 3. Configure
cp .env.example .env # then edit: fill in JAMA_URL / JAMA_CLIENT_ID / JAMA_CLIENT_SECRET
# Or run the interactive wizard (also lets you choose the DB storage directory):
# uv run python setup_wizard.py
# 4. Pre-download models (~150 MB ONNX, one-time)
uv run python bootstrap.py
# 5. Run
uv run python server.py # stdio (default) — local MCP client spawns itpippip install -r requirements.txt
cp .env.example .env # fill in Jama credentials
python bootstrap.py
python server.pyThe server supports three transports, selected by JAMA_MCP_TRANSPORT:
Transport | Use case | Client connects via |
| Local MCP client (Claude Desktop) spawns server as subprocess | stdin/stdout |
| Remote client / Docker / shared server |
|
| Older MCP clients that only support SSE |
|
For HTTP/SSE mode, set JAMA_MCP_HOST (0.0.0.0 for remote access) and
JAMA_MCP_PORT (default 8000):
# streamable-http (MCP new standard), listening on all interfaces
JAMA_MCP_TRANSPORT=streamable-http JAMA_MCP_HOST=0.0.0.0 uv run python server.py
# SSE (older clients)
JAMA_MCP_TRANSPORT=sse JAMA_MCP_HOST=0.0.0.0 uv run python server.py{
"mcpServers": {
"jama-mcp": {
"command": "uv",
"args": ["run", "--directory", "/abs/path/to/jama", "python", "server.py"]
}
}
}Point your MCP client at http://localhost:8000/mcp (or the remote host:port).
To (re)download just the models later without re-running the wizard:
uv run python bootstrap.py # or: python bootstrap.pyThe models live in user/huggingface/ (project-local, ~150 MB: a ~130 MB
ONNX embedding + ~80 MB ONNX cross-encoder reranker). Both run on onnxruntime
via fastembed — CPU-only, no torch/transformers. The model files are plain
data — portable across machines, so you can copy that folder from another
machine to skip the download entirely.
onnxruntime is pinned to 1.20.1 and Python 3.13+ is not supported
(requires-python = ">=3.10,<3.13"). On Windows, onnxruntime ≥1.21 (which
Python 3.13 forces, because fastembed requires >1.21 there) depends on the
new VC++ Runtime (vcruntime140_1.dll) absent on many machines, causing
WinError 1114 DLL load failures. 1.20.1 loads cleanly on Python 3.10–3.12
and satisfies fastembed's constraint. uv sync automatically picks Python
3.12 (the verified stable target) from the lockfile. If you upgrade
onnxruntime, re-test on a clean Windows machine without the latest VC++
Redistributable.
onnxruntime is a C++ binary that needs vcruntime140.dll — part of the
Microsoft VC++ Redistributable. Most Windows machines already have it
(anything with Chrome / Java / VS Code installed does), but a clean Windows
install may not.
The server auto-detects this: preflight probes for the DLL and, if
missing, reports a clear blocking error with the fix. setup_wizard.py
offers to auto-install it (downloads the 24 MB installer from
https://aka.ms/vs/16/release/vc_redist.x64.exe — reachable from mainland
China at ~420 KB/s — and runs it silently). You can also install it manually:
# From the project directory (after uv sync):
uv run python -c "from preflight import install_vcruntime; install_vcruntime()"
# Or download + run the installer yourself:
# https://aka.ms/vs/16/release/vc_redist.x64.exeThis is a system-level install (writes vcruntime140.dll to
C:\Windows\System32, requires admin/UAC) — it's the one thing this project
installs outside its own folder, because the DLL must be in the system path
for onnxruntime to find it. Linux/macOS don't need it (onnxruntime bundles
the system libs in its wheels there).
After the server starts, the LLM client should call bootstrap_models (and poll
get_bootstrap_progress every ~2 min) to pre-download the embedding + reranker
models BEFORE the first init_jama_project — see Model bootstrap.
On startup the server logs a hint if the models aren't cached yet.
Every MCP tool runs an offline pre-flight check before doing any work:
Python dependencies, required env vars (JAMA_URL / JAMA_CLIENT_ID /
JAMA_CLIENT_SECRET — plus EMBEDDING_BASE_URL / EMBEDDING_API_KEY only when
EMBEDDING_PROVIDER=azure; the default local CPU provider needs no embedding
credentials) and the SQLite store. If anything is missing the tool returns a
clear error dict with a hint instead of failing midway through a Jama API
call. Configure via the wizard, or call the configure_jama / validate_setup
tools at runtime.
{
"mcpServers": {
"jama-mcp": {
"command": "python",
"args": ["/absolute/path/to/jama-mcp-server/server.py"],
"env": { "JAMA_MCP_DB_PATH": "/absolute/path/to/jama-mcp-server/jama_mcp.db" }
// ↑ DB directory is selectable at install time via setup_wizard; filename is fixed.
}
}
}bootstrap_models() → pre-download embedding + reranker models (first run
only). Returns job_id immediately; poll get_bootstrap_progress(job_id)
every ~2 min until DONE. Skip if models are already cached (re-running is
a fast no-op).
init_jama_project("20571") → returns job_id immediately (non-blocking).
get_sync_progress(job_id) → poll until status == "DONE", roughly every
2 minutes (syncs index many items and take minutes — don't busy-poll).
search_jama_semantics("20571", "how does volume sync work", top_k=5) → RAG.
query_jama_native_metadata("20314", document_key="SA-TC-7") → exact match.
To re-index a project that is already initialized, use
reinit_jama_project("20571") (full re-sync) and poll the same way. Scheduled
incremental syncs run automatically (~every 2h); check any project's in-flight
job plus its last init/reinit/sync run at any time with
get_sync_status("20571").
The embedding model (~130MB ONNX, bge-small-en-v1.5) and the cross-encoder
reranker (~80MB) are not bundled — they download on first use. To keep the
first sync from stalling on a model download, call bootstrap_models right
after the server is configured. It downloads BOTH models asynchronously (a
kind="bootstrap" job in sync_jobs, run on the same thread pool as syncs) and
returns a job_id immediately.
bootstrap_models() — start the async pre-download (no-op per model if
already cached). Reentrancy-guarded: a second call while one is RUNNING
returns the existing job_id.
get_bootstrap_progress(job_id) — poll every ~2 min. Progress is
phase-based, not live bytes: the reranker downloads via
snapshot_download and the embedding via fastembed, neither of which gives a
per-chunk byte callback, so message reports phase transitions (e.g.
"Downloading reranker model (...)" → "Reranker model ready") rather than byte
counts. status → DONE (both cached) or ERROR.
On startup, if either model isn't cached, the server logs a hint to call
bootstrap_models. The sync-time ensure_downloaded calls remain as a fallback
so a skipped bootstrap still works (the first sync downloads the models inline).
get_sync_status(project_id) is the one-call monitor for a project's sync
operations. All three operations — init_jama_project, reinit_jama_project
and the scheduled incremental sync — run asynchronously as background jobs
(recorded in the sync_jobs table with kind = init / reinit / sync),
so each is pollable. The tool returns:
active_job — the in-flight job for this project (or null if idle);
recent.{init,reinit,sync} — the most recent job of each kind, terminal or
running, so you can see the last result even when nothing is running now;
project_status / last_sync_time / item_count / chunk_count — current
project state;
process — lightweight live metrics (RSS, threads, DB size, chunk count) for
the server process; null if psutil is unavailable.
After starting an init or reinit, poll get_sync_progress(job_id) (or
get_sync_status(project_id)) roughly every 2 minutes, reporting each sample
to the user, until the job reaches DONE/ERROR. On startup, any job left
RUNNING by a prior crash is reconciled to ERROR (interrupted by restart)
so the monitor never shows a phantom in-flight job.
Jama API: OAuth token auto-refresh on expiry + 401 retry; urllib3 Retry
with exponential backoff on 429/5xx; explicit Retry-After handling; SSL
connection-reset tolerated (transient on this network).
Embeddings: same retry/backoff session on the embedding endpoint.
SQLite concurrency: WAL mode + busy timeout + a process-level write lock
so the APScheduler writer and MCP reader threads coexist without
SQLITE_BUSY errors; chunk replacement is atomic per item.
Reranker: lazy-loaded singleton; failure degrades to RRF-only scoring instead of crashing the search.
Read-only: JamaClient only issues GET requests — it cannot create,
modify or delete data on the Jama instance.
File | Purpose |
| deps + Aliyun mirror config |
| env-driven settings (dataclasses) + validation/persistence/reload |
| SQLite schema, FTS5 + sqlite-vec loading, CRUD |
| OAuth, paginated fetch, HTML cleaning, native query, browse API |
| chunking, embeddings, Multi-Query, hybrid recall, RRF, rerank |
| MCP tools, async jobs, APScheduler incremental sync, pre-flight guards |
| offline dependency + config + storage validation |
| pre-download bandwidth speed test ( |
| foreground model pre-download CLI ( |
| interactive configuration wizard ( |
| end-to-end self-test suite ( |
| template for environment configuration |
Configuration & validation
validate_setup(live=False) — offline pre-flight (+ optional live Jama/embedding probe).
configure_jama(values) — apply config at runtime, persist to .env, reload.
Jama browse (read-only, gated by pre-flight)
list_jama_projects() — all visible projects.
find_jama_project_by_name(name, exact?) — find projects by name → get id + info.
get_jama_item(item_id) — full single item (cleaned text).
get_jama_item_children(item_id) — decomposition children.
get_jama_item_relationships(item_id) / list_jama_project_relationships(project_id, item_id?) — relationships (cursor-paginated /relationships).
get_jama_item_comments(item_id) — item comments (cleaned body).
get_jama_item_attachments(item_id) — attachment metadata (no binary).
list_jama_releases(project_id) — project releases/versions.
list_jama_test_runs(project_id?, test_cycle_id?) — test runs.
list_jama_item_types() — tenant item types (id → name).
find_jama_item_type_by_name(name, exact?) — find item types by display name → get the id needed by item_type filters.
query_jama_endpoint(path, params?, all_pages?) — generic read-only GET escape hatch.
RAG / retrieval / sync monitoring
bootstrap_models() — async pre-download of embedding + reranker models (returns job_id).
get_bootstrap_progress(job_id) — poll a bootstrap job (every ~2 min) until DONE/ERROR.
init_jama_project(project_id) — async background init (returns job_id).
reinit_jama_project(project_id) — async full re-sync of an already-initialized project.
get_sync_progress(job_id) — poll one init/reinit/sync job's progress.
get_sync_status(project_id) — project monitor: in-flight job + last init/reinit/sync run + process metrics.
search_jama_semantics(project_id, query, ...) — Multi-Query + hybrid + RRF + cross-encoder rerank.
query_jama_native_metadata(project_id, ...) — exact-match metadata via /abstractitems.
All components self-tested against the live Jama instance and the local CPU embedding backend: OAuth + paginated fetch, HTML→text cleaning, Test Case step rendering, item-type mapping, DB schema (FTS5 + vec0), full RAG search, async init with progress polling, incremental sync (0 new items), concurrent download + batched embed, crash recovery (INITIALIZING → auto-resynced READY), native metadata filters (item_type / status / keyword / document_key), APScheduler startup, MCP stdio handshake, and error paths (bad project id, unknown job, nonexistent project, missing args).
The cross-encoder reranker (ms-marco-MiniLM-L-6-v2, ONNX port via
fastembed) was downloaded from the HuggingFace China mirror (hf-mirror.com)
and loaded on onnxruntime (no torch); verified it produces non-zero relevance
scores with correct ordering (a related document scores significantly higher
than an unrelated one) and that the end-to-end RAG search returns
strategy=rerank results. Scores are the model's raw logits (may be
negative) — only the relative order is meaningful for re-ranking. LlamaIndex is the
primary RAG framework: SentenceSplitter + Document/TextNode for chunking.
Multi-Query expansion is performed by the MCP LLM client and passed to the
pipeline via search(sub_queries=...); when omitted, deterministic lexical
variants are used.
Pre-download the embedding model (and optionally the reranker) so syncs never wait on them.
Downloads the local embedding model (bge-small-en-v1.5, ~130MB ONNX) into
the project-local cache, ASYNCHRONOUSLY, via onnxruntime/fastembed (no
torch/transformers dependency). Returns a job_id immediately. This is the
recommended first step after installing/configuring the server — call it
BEFORE init_jama_project so the first sync isn't slowed by a model
download. Models already cached are skipped. Poll progress with
get_bootstrap_progress roughly every 2 minutes, reporting each sample to
the user, until status is DONE or ERROR.
The cross-encoder reranker (ms-marco-MiniLM-L-6-v2, ~80MB ONNX) is only
downloaded when explicitly enabled via RERANKER_ENABLED=1. The default
search path is pure RRF ordering (benchmarking showed it outperforms
rerank), so a default install needs NO reranker weights and bootstrap
completes after the embedding model alone.
Returns:
{"job_id": "...", "status": "RUNNING"} or, if a bootstrap is already
running, {"job_id": "...", "status": "RUNNING", "note": "..."}.
| 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 full burden. Discloses asynchronous download, caching behavior, reranker toggle via environment variable, and default RRF ordering avoiding reranker need.
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?
Well-structured with clear paragraphs and bullet points for return values. Concise yet comprehensive, no superfluous 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?
Covers model details, caching, polling advice, return format, and reranker toggle. Complete for a setup tool with no output 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?
No parameters exist, baseline 4. Description adds value by clarifying default behavior regarding reranker but no parameter details needed.
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 it pre-downloads embedding model and optional reranker to avoid wait during syncs. Specifies model names and sizes, and distinguishes from sibling tools like init_jama_project.
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 states it's the recommended first step after installing/configuring the server, call BEFORE init_jama_project. Also explains when reranker is needed and suggests polling with get_bootstrap_progress.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply configuration values at runtime and persist them to .env.
Accepts a mapping of env-var names to values (e.g.
``{"JAMA_URL":"...","JAMA_CLIENT_SECRET":"..."}`). Writes a complete
``.env`` (merging with existing values), reloads settings in-process, and
resets the Jama/RAG/DB singletons so subsequent calls use the new config.
Secrets are written to ``.env`` on disk only; they are never echoed back.
Args:
values: dict of {ENV_VAR: value}. Recognized keys: JAMA_URL,
JAMA_CLIENT_ID, JAMA_CLIENT_SECRET, EMBEDDING_BASE_URL,
EMBEDDING_API_KEY, JAMA_MCP_DB_PATH,
and any other key in the .env template.
Returns:
{"ok": true, "written": <abs .env path>, "applied_keys": [...]}
or {"error": ...}
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully handles transparency. It discloses that the tool writes to .env, merges with existing values, reloads settings, and resets singletons. It also notes secrets are never echoed back. This is fairly comprehensive, though it could mention side effects like overwriting existing values.
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 and well-structured with Args and Returns sections. Every sentence adds value, and there is no redundant information. It is efficient for the agent to parse.
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 (modifying persistent state, resetting singletons), the description covers essential aspects: input format, merge behavior, security (no secret echo), and return schema. However, it does not address error scenarios beyond returning an error dict, nor does it mention prerequisites or potential permission issues.
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 schema only defines a generic object with additionalProperties. The description adds significant meaning by listing recognized keys (JAMA_URL, etc.), stating it accepts a mapping, and noting that any key from the .env template is valid. This helps the agent understand parameter structure and valid keys.
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 applies configuration values at runtime and persists them to .env. It uses specific verbs ('apply', 'persist') and identifies the resource (configuration). Sibling tools like bootstrap_models or search functions are clearly distinct.
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 the tool (to apply configuration values) but does not explicitly state when not to use it or suggest alternatives. However, given the sibling set, it's evident that this is the only configuration tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Jama item types by display name (case-insensitive) and return info.
Returns the type id (needed by search_jama_semantics / query_jama_native_metadata
item_type filters) plus category, display plural and description. Matching is
substring by default; pass exact=True for full case-insensitive equality.
Args:
name: type name or fragment (e.g. "test" matches "Test Case", "Test Plan").
exact: if True, require full case-insensitive name equality.
limit: max matches to return (default 20).
Returns:
{"count","results":[{id,display,display_plural,category,category_name,
description}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| exact | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses the tool's behavior: case-insensitive matching, substring vs exact search, limit parameter, and the exact return structure (count, results with id, display, etc.). No contradictions or omissions.
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 yet thorough, with the main purpose front-loaded. The Args section is clearly structured, each parameter is explained in one line, and the Returns section is explicit. No extraneous text.
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 lookup tool with no output schema, the description provides complete information: purpose, parameter details, matching behavior, return format, and linkage to other tools. Nothing essential is missing.
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 input schema has 0% description coverage, so the description compensates fully. It explains the name parameter with an example ('test' matches 'Test Case'), clarifies the exact parameter (default false, full case-insensitive equality when true), and specifies the limit default (20). This adds significant meaning 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's purpose: 'Find Jama item types by display name (case-insensitive) and return info.' It specifies the verb 'find' and resource 'Jama item types', and distinguishes itself from siblings like 'list_jama_item_types' by focusing on searching by name rather than listing all.
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 the tool returns type IDs needed for item_type filters in other tools (search_jama_semantics, query_jama_native_metadata), providing clear context for when to use it. It also describes matching behavior (substring vs exact) and default limit, but does not explicitly list when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Jama projects by name (case-insensitive) and return their info.
Useful when you only know a project's name (or a fragment of it) and need
its numeric id to feed into other tools (init_jama_project,
list_jama_releases, list_jama_test_runs, …). Matching is substring by
default; pass exact=True for full case-insensitive equality.
Args:
name: project name or fragment (e.g. "acre" matches "Acrelec").
exact: if True, require full case-insensitive name equality.
limit: max matches to return (default 20).
Returns:
{"count","results":[{id,project_key,name,status,description}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| exact | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses case-insensitive and substring matching behavior, plus the effect of exact parameter. Describes return format. No annotations provided, so description carries full burden; it adequately covers key traits but could mention if operation is read-only (likely) and any rate limits.
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?
Well-organized with Args and Returns sections. Front-loaded purpose in first line. Every sentence adds value; 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 no annotations or output schema, description fully covers tool purpose, parameter behavior, return format, and usage context for downstream tools. No gaps for this simple lookup 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?
Adds significant value beyond schema: explains name is a fragment by default, exact parameter controls full match, limit caps results. Schema has 0% description coverage, so description fully compensates with detailed semantics and examples.
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 verb 'Find' and resource 'Jama projects by name', with case-insensitive matching. Distinguishes from sibling list_jama_projects by focusing on name-based lookup to get IDs for other tools.
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 says when to use: when only project name is known and numeric ID is needed for other tools. Provides context on substring vs exact matching. Could be improved by explicitly stating when not to use (e.g., if ID already known), but implication is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll the progress of a bootstrap_models job.
After calling bootstrap_models, poll this roughly every 2 minutes, reporting
each sample (status, progress %, message) to the user, until status is DONE
or ERROR. Progress is phase-based, not live bytes: the embedding
(~130MB ONNX, via fastembed) lacks per-chunk byte callbacks, so `message`
reports phase transitions rather than byte counts. When the reranker is
enabled (RERANKER_ENABLED=1) a second phase downloads the ~80MB reranker;
otherwise bootstrap completes after the embedding model alone.
Returns:
{"job_id","project_id","kind","status","progress","total","done",
"message","started_at","finished_at"} (project_id is 0 for a
bootstrap job — it has no project). status is one of
PENDING | RUNNING | DONE | ERROR.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It fully discloses that progress is phase-based not live bytes, explains the embedding and reranker phases with sizes, and lists return fields and status values.
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 well-structured with a clear first line stating purpose, then usage, then technical details. It is somewhat lengthy but each sentence adds value. Could be slightly more concise.
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 polling tool with phases and no output schema, the description is very complete. It explains behavior, return fields, status enum, and edge case (project_id=0 for bootstrap jobs). No missing information.
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 single parameter job_id is not described in the description (schema coverage 0%). The name is self-explanatory but the description could have clarified where to obtain it (e.g., from bootstrap_models response). Minimal added value beyond 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 verb 'Poll' and the resource 'progress of a bootstrap_models job'. It is distinct from sibling tools like bootstrap_models (which starts the job) and others.
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 tells the agent to poll after calling bootstrap_models, with a recommended interval of 2 minutes, and to report until status DONE or ERROR. Also explains the phase-based progress and reranker behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single Jama item by id (full metadata + cleaned text).
Args:
item_id: numeric string Jama item id.
Returns:
{"item":{item_id,document_key,item_type_name,name,status,
description,test_steps,modified_date,...}}
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It describes a read operation ('Fetch') and mentions return format, but lacks details on permissions, error handling, or potential side effects. Adequate but minimal.
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?
Description is concise with no unnecessary words. It efficiently conveys purpose, arguments, and return format in a structured block.
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 single-item fetch, description covers input and output. However, it omits error cases (e.g., item not found) and does not mention any special behavior. Acceptable but not fully 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%, but description adds 'numeric string Jama item id' for the item_id parameter, which clarifies type and meaning. This compensates well for the missing schema descriptions.
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?
Description clearly states 'Fetch a single Jama item by id (full metadata + cleaned text)', specifying the verb, resource, and input. This distinguishes it from siblings like get_jama_item_attachments or get_jama_item_children.
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 guidance on when to use this tool versus alternatives. Does not specify prerequisites, when not to use, or mention other tools for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List attachment metadata for an item (no binary download).
Args:
item_id: numeric string Jama item id.
limit: max attachments to return (default 50).
Returns:
{"item_id","count","results":[{id,name,file_type,file_size,
mime_type,created_date,modified_date}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description indicates the operation is read-only ('no binary download') and describes the return format. However, it does not disclose authentication needs, rate limits, or potential side effects.
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 very concise with a clear purpose statement, followed by a structured Args and Returns sections. Every sentence adds value without 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 no output schema, the description documents the return structure. It covers the tool's purpose, parameters, and output format. Minor missing details like pagination or error handling, but adequate for a simple list 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 coverage is 0%, so description carries the full burden. It explains 'item_id' as a numeric string and 'limit' as max attachments with default 50, adding meaning beyond the schema types.
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 explicitly states the tool lists attachment metadata for an item, and clarifies it does not include binary download. This clearly distinguishes it from other tools in the sibling list like get_jama_item or search tools.
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 provides basic usage through Args, but lacks explicit guidance on when to use this tool versus alternatives. No 'when not to use' or comparison to siblings is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List decomposition children of an item.
Args:
item_id: numeric string Jama item id.
limit: max children to return (default 50).
Returns:
{"item_id","count","results":[{item_id,document_key,item_type_name,
name,status,modified_date}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals the return format and the limit parameter behavior (default 50). Since no annotations are provided, this is sufficient to understand the tool's read-only nature and output structure.
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 a front-loaded purpose, followed by structured Args and Returns sections. 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?
The description covers input parameters and return format adequately for a simple tool. However, it does not clarify if 'children' refers to direct children or all descendants, which could be ambiguous.
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 Args section adds meaning beyond the schema: it specifies that item_id is a 'numeric string' and limit has a default of 50. This compensates for the 0% schema description coverage.
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 'List decomposition children of an item', specifying the verb and resource. It distinguishes from sibling tools like 'get_jama_item' which retrieves a single item, and other get_* tools.
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 guidance on when to use this tool versus alternatives. For example, no mention of scenarios where 'get_jama_item_relationships' or 'search_jama_semantics' would be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List comments threaded on an item.
Args:
item_id: numeric string Jama item id.
limit: max comments to return (default 50).
Returns:
{"item_id","count","results":[{id,body,created_by,created_date,
modified_date}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It implies read-only operation but does not explicitly state non-destructive nature or any behavioral traits beyond the return format.
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?
Extremely concise: one-line purpose, then two parameters and a return format. Every sentence is relevant, front-loaded, and no extraneous text.
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 provides the return format in text since no output schema exists. Complexity is low. Could mention ordering or pagination, but adequate for this simple 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 coverage is 0%, but the description adds meaning: item_id as 'numeric string Jama item id' and limit as 'max comments to return (default 50)'. This enriches the schema beyond just types.
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 states 'List comments threaded on an item,' which is a specific verb and resource. It clearly distinguishes from siblings like get_jama_item and get_jama_item_attachments.
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 guidance on when to use this tool versus alternatives. The purpose is implied but no exclusions or context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List relationships (source/target) for an item.
Args:
item_id: numeric string Jama item id.
limit: max relationships to return (default 50).
Returns:
{"item_id","count","results":[{id,relationship_type,source_item,
target_item,name,modified_date}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full disclosure burden. It states it lists relationships (a read operation) and returns specific fields, but omits behavioral details such as pagination behavior beyond the default limit, authentication requirements, or potential performance impacts for large items.
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 (4 lines plus return format) and starts with the core purpose. However, the Python docstring style with 'Args:' and 'Returns:' adds slight verbosity but remains 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?
For a simple tool with 2 parameters and no output schema, the description covers purpose, parameter defaults, and return structure. It could include an example or note on cursor/pagination, but overall it suffices for effective use.
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%, meaning the description must compensate. However, it merely restates parameter names (item_id, limit) and the default for limit, adding no extra meaning about format, constraints, or how to specify numeric strings. The return format is provided, but parameter semantics remain shallow.
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 starts with 'List relationships (source/target) for an item,' clearly stating the verb (list) and resource (relationships of an item). Among siblings like get_jama_item_children, get_jama_item_comments, this tool is uniquely about relationships, making its purpose distinct.
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 provides parameter details but offers no guidance on when to use this tool versus alternatives like get_jama_item_children or get_jama_item_comments. No exclusions or context about relationship scenarios are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll the progress of an init, reinit or sync job.
After calling init_jama_project or reinit_jama_project, poll this roughly
every 2 minutes until status is DONE or ERROR, reporting each sample to the
user. For a project-wide view of all operations and their last runs, use
get_sync_status instead.
Returns:
{"job_id","project_id","kind","status","progress","total","done",
"message","started_at","finished_at"}
status is one of PENDING | RUNNING | DONE | ERROR.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers polling behavior, return fields, and status values. Lacks permission details but adequate for a simple polling 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?
Concise: 4 sentences with return fields listed. Front-loaded purpose, 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?
Complete for a single-param polling tool with no output schema: covers purpose, usage pattern, alternative, and return structure.
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 has 0% description coverage, but description implies job_id is from init/reinit. Does not explicitly document format or source, but context is sufficient.
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 polls progress of init/reinit/sync jobs. It specifies the verb 'poll', the resource 'progress', and distinguishes from get_sync_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?
Explicitly says to poll every 2 minutes after specific calls until status is DONE or ERROR, and to report to user. Also names get_sync_status as alternative for project-wide view.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Monitor a project's sync operations: current run + last run of each kind.
Use this to check on init_jama_project / reinit_jama_project / scheduled
sync for one project. It returns the in-flight job (if any), the most recent
init / reinit / sync job (terminal or running), the project's current state,
and lightweight process metrics. After starting an init or reinit, you may
poll this roughly every 2 minutes (reporting each sample to the user) until
active_job is null and the relevant recent.* entry is DONE/ERROR.
Args:
project_id: Jama project id (numeric string, e.g. "20571").
Returns:
{"project_id","project_status","last_sync_time","item_count",
"chunk_count","active_job": {...}|null,
"recent": {"init": {...}|null, "reinit": {...}|null,
"sync": {...}|null},
"process": {"rss_mb","threads","db_mb","chunks"}|null}
Returns {"error": ...} if the project_id is not numeric or the server
is not ready.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses return structure (active_job, recent jobs, process metrics) and error conditions (non-numeric project_id, server not ready). This is thorough for behavioral 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?
The description is fairly long but well-structured with sections for usage, parameters, and return format. It's not overly verbose and front-loads the purpose. Minor redundancy could be trimmed.
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, the description fully explains the return structure and error cases. It covers purpose, usage, parameters, and polling behavior, making it complete for an agent to use 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 coverage is 0% (only title), so description compensates by explaining project_id is a numeric string with example (e.g., '20571'). This adds meaning beyond the schema's type definition.
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 monitors sync operations, specifying 'current run + last run of each kind'. It uses a specific verb ('monitor') and resource ('sync operations'), distinguishing it from sibling tools like get_sync_progress.
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 (after init/reinit/sync) and provides polling instructions (every 2 minutes). It implies context but does not explicitly list when not to use or alternatives, though it's clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize a Jama project: download, clean, vectorize and index its items.
Runs as an async background task and returns a job_id immediately so the
caller (LLM) is never blocked. Poll progress with get_sync_progress roughly
every 2 minutes until status is DONE or ERROR, reporting each sample to the
user. To re-index a project that is already initialized, prefer
reinit_jama_project.
Args:
project_id: Jama project id (numeric string, e.g. "20571").
Returns:
{"job_id": "...", "project_id": ..., "status": "RUNNING"}
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description clearly explains async behavior and polling requirement. Could mention potential side effects or failure modes, but overall adequate.
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?
Concise, front-loaded with purpose. Every sentence adds value: async note, polling instructions, sibling tool advice, args and returns. 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?
Covers purpose, behavior, parameters, and return format. Lacks prerequisites (e.g., project must exist) but sufficient for a single-parameter async tool with no output 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?
Adds beyond schema: describes project_id as 'numeric string' with example '20571'. Schema only defines type string. Description provides format and usage context.
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?
States 'Initialize a Jama project: download, clean, vectorize and index its items', which is a specific verb-resource pair. Differentiates from sibling reinit_jama_project by explicitly advising its use for already initialized projects.
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?
Provides explicit instructions: runs async, returns job_id, poll with get_sync_progress every 2 minutes, report samples to user. Also tells when to use sibling reinit_jama_project instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Jama item types (id -> display name) for the tenant.
Returns:
{"count","results":[{id,name}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only mentions return format. Does not disclose behavioral traits such as read-only nature, authorization needs, or performance characteristics.
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?
Extremely concise (two lines), no redundant information, and effectively communicates core functionality.
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 simplicity (no parameters, no output schema), the description is adequate, specifying return format. No critical information missing.
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?
Tool has zero parameters, so baseline 4 applies. Description adds no parameter-specific info, but none is needed.
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?
Description clearly states 'List all Jama item types (id -> display name) for the tenant,' using a specific verb and resource. It distinguishes from sibling tools like find_jama_item_type_by_name.
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?
Implied usage (when a mapping of all item types is needed) but no explicit when-not-to-use or comparison with alternatives like find_jama_item_type_by_name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List relationships for a project (cursor-paginated Jama endpoint).
Jama's ``/relationships`` endpoint requires a ``project`` filter and uses
``lastId`` cursor pagination. Optionally filter to relationships involving
a specific item (client-side on fromItem/toItem).
Args:
project_id: numeric string Jama project id.
item_id: optional numeric string item id to filter on.
limit: max relationships to return (default 50).
Returns:
{"project_id","count","results":[{id,relationship_type,source_item,
target_item,suspect,name,modified_date}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| item_id | No | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Covers pagination (lastId cursor), optional client-side filtering, and return format. Without annotations, it provides sufficient behavioral context for a list 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?
Concise with front-loaded purpose. Each sentence adds value (purpose, endpoint details, args, returns). Minor redundancy but 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?
Complete for a list tool: explains pagination, filtering, and return format. With no output schema, it provides the necessary structure. All parameters documented.
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?
Adds meaning beyond the input schema: explains project_id as numeric string, item_id as optional, limit with default 50. Schema coverage was 0%, so description fully compensates.
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?
Description clearly states 'List relationships for a project' and explains the cursor-paginated endpoint. It distinguishes from sibling tools like 'get_jama_item_relationships' by indicating that item filtering is optional and client-side, implying the project-level scope.
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?
Description specifies when to use (project-level listing) and notes client-side filtering, cautioning about efficiency. However, it does not explicitly name alternative siblings or state when not 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.
List all Jama projects visible to the OAuth client.
Returns:
{"count","results":[{id,project_key,name,status,description}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses it's a read operation listing projects, but omits details like pagination, rate limits, or any potential limitations. Adequate for a simple list tool but could be more 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?
Two sentences: first states purpose, second details return format. No redundant information, very 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?
For a simple list tool with no parameters and no output schema, the description provides the return structure. However, it doesn't mention if the list is paginated or sorted, which could be relevant for large datasets.
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?
No parameters exist, so the description adds value by explaining the return format and what is listed. Baseline for zero parameters is 4.
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 'List', the resource 'Jama projects', and the scope 'visible to the OAuth client'. It distinguishes from sibling 'find_jama_project_by_name' which searches by name.
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 guidance on when to use this tool vs alternatives. While the description implies it lists all projects (contrast with find_jama_project_by_name), it doesn't state conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List releases / versions for a project.
Args:
project_id: numeric string Jama project id.
limit: max releases to return (default 50).
Returns:
{"project_id","count","results":[{id,name,release_date,status,
description,modified_date}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| project_id | 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 describes the return format and default limit, but lacks details on side effects, authentication needs, error handling, or whether the operation is read-only.
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 a clear docstring format: brief sentence, Args section, Returns section. No redundant or missing information.
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 no output schema, the description provides the return structure and parameter details. However, it omits error conditions, pagination behavior beyond limit, and assumes the project exists. Good but not fully comprehensive.
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%, but the description adds meaning: project_id is described as 'numeric string Jama project id' and limit as 'max releases to return (default 50)'. This goes beyond the schema labels. Could be improved by specifying allowed values or project_id format.
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?
Description clearly states 'List releases / versions for a project', using a specific verb and resource. This distinguishes it from sibling tools like list_jama_projects which list projects instead of releases.
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 implies usage by explaining the project_id and limit parameters, but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List test runs for a project and/or test cycle.
At least one of ``project_id`` / ``test_cycle_id`` must be provided.
Args:
project_id: optional numeric string Jama project id.
test_cycle_id: optional numeric string Jama test cycle id.
limit: max test runs to return (default 50).
Returns:
{"count","results":[{id,name,status,test_cycle,item,assigned_to,
modified_date}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| project_id | No | ||
| test_cycle_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes return format and default limit but omits potential errors (e.g., invalid IDs), authentication, or pagination behavior. Adequate for a read-only list 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?
Very concise: one sentence for purpose, one for requirement, then Args section with brief explanations. No wasted words, well-organized.
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 3 parameters, no output schema, and no annotations, the description covers purpose, parameters, and return structure. Could mention error handling when both IDs missing, but overall sufficient.
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%, but description adds meaning: explains each parameter as optional numeric strings, limit as max test runs with default. This compensates for schema's lack of descriptions.
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's verb and resource: 'List test runs for a project and/or test cycle.' It specifies scope via optional parameters, distinguishing it from sibling tools like list_jama_projects or list_jama_releases.
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 condition provided: 'At least one of project_id / test_cycle_id must be provided.' The limit parameter and its default are described. No explicit when-not-to-use or alternatives, but clear enough for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Power-user escape hatch: GET any Jama REST endpoint (read-only).
``path`` is appended to ``{JAMA_URL}{API_PREFIX}`` (e.g. ``"/projects"``).
Only GET is ever issued; the client is read-only by design.
Args:
path: REST path beginning with '/', e.g. "/items/12345".
params: optional 'k1=v1&k2=v2' query string.
all_pages: if True, walk all pages and return a flat list of ``data``;
if False (default), return only the first page.
Returns:
{"path","data": <first-page data or flat list>}
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| params | No | ||
| all_pages | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Details the behavior: appends path to base URL, can walk all pages with all_pages flag, returns flat list. Lacks mention of rate limits or errors, but for a generic power-user tool this is acceptable.
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?
Well-structured with separate sections for general description, args, and returns. Slightly verbose but still efficient. Could be more concise, but structure aids readability.
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?
Covers key aspects: path format, query string syntax, pagination, return value. No output schema but return described. Complete enough for a generic API tool, though could mention potential errors (e.g., 404).
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%, but description compensates fully: explains path format, optional params query string, all_pages behavior. Also describes return format. All parameters are clearly semantically defined.
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?
Description clearly states it's a power-user escape hatch for GET requests on any Jama REST endpoint (read-only). This distinguishes it from sibling tools that target specific endpoints.
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 notes that only GET is issued and the client is read-only, providing guidance on when to use. Could be more explicit about when not to use (e.g., for writes), but the 'read-only' warning is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query Jama's native REST API directly for exact metadata filtering.
Use ONLY for precise lookups (exact document key, exact status, exact
item_type) — it returns empty on any misspelling. For topical, fuzzy or
natural-language questions, prefer `search_jama_semantics` instead.
Bypasses the vector store to answer precise questions (exact document key,
specific status, specific item type). Handles pagination internally and
returns up to 20 core metadata records.
Args:
project_id: numeric string Jama project id.
document_key: exact Jama document key (e.g. "SA-TC-7").
item_type: Jama item-type id as a numeric string (e.g. "89011" for Test
Case). Pass None for all types. Kept as a string (not int)
to match `search_jama_semantics` and the other MCP tools,
which all take ids as numeric strings.
status: exact status string (e.g. "BLOCKED", "APPROVED").
keyword: full-text 'contains' filter delegated to Jama.
Returns:
{"project_id","count","results":[{document_key,name,item_type_name,
status,modified_date,description}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| keyword | No | ||
| item_type | No | ||
| project_id | Yes | ||
| document_key | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full weight. It discloses bypassing vector store, internal pagination, 20-record limit, and return structure. Lacks details on error handling, rate limits, or authentication, but adequate for a read-only query 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?
Well-structured with summary line, usage guidelines, behavior, parameter details, and return format. Slightly verbose but each sentence adds value. No redundant information.
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?
Covers purpose, usage, parameters, behavior, and return format. Mentions pagination and result limit. Minor gaps: no error handling or edge cases. Good for 5-parameter tool without output 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% with 5 parameters and no descriptions. Description explains each parameter: project_id, document_key, item_type (string consistency rationale), status (example values), keyword (full-text filter). Fully compensates for missing schema descriptions.
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?
Description clearly states verb 'Query' and resource 'Jama's native REST API' with purpose 'exact metadata filtering'. It distinguishes from sibling 'search_jama_semantics' by specifying precise vs. fuzzy usage.
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 says 'Use ONLY for precise lookups' and directs to 'search_jama_semantics' for fuzzy queries. Also warns about empty results on misspelling, providing clear when-to and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-initialize an already-initialized Jama project (full re-sync).
Behaves like init_jama_project but is the explicit verb for re-fetching and
re-indexing a project that has already reached READY/ERROR — e.g. after a
config change, corrupted index, or to pull a fresh full copy. Runs as an
async background task and returns a job_id immediately. Poll progress with
get_sync_progress roughly every 2 minutes until status is DONE or ERROR,
reporting each sample to the user.
Args:
project_id: Jama project id (numeric string, e.g. "20571").
Returns:
{"job_id": "...", "project_id": ..., "status": "RUNNING"}
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses async background execution, immediate return of job_id, suggested polling interval, and expected final statuses (DONE/ERROR). Exceeds requirements.
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?
Well-structured with a clear summary, usage context, polling instructions, and Args/Returns sections. Every sentence is informative and earns its place.
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 provides return format. Covers async behavior, polling guidance, and typical use cases. Fully sufficient for an agent to invoke and monitor 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?
Single parameter project_id is explained with type (string, numeric) and example. Adds meaning beyond schema minimal definition.
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?
Description explicitly states 'Re-initialize an already-initialized Jama project (full re-sync)' and differentiates from init_jama_project by specifying it is for projects already in READY/ERROR states.
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?
Describes situations to use (config change, corrupted index, fresh copy) and mentions polling with get_sync_progress. Lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search over an initialized Jama project using high-precision RAG.
This is the DEFAULT tool for any non-precise question. It fuses keyword
(FTS5/BM25), vector (sqlite-vec cosine) and RRF in one call — so "like",
"keyword" and "semantic" queries are all best answered here. Prefer it over
native metadata unless the user gives an exact document key / status / item id.
Pipeline: client Multi-Query expansion -> hybrid recall (sqlite-vec +
FTS5) -> RRF fusion (with item-level dedup) -> top_k results. Ranking is
pure RRF by default: the cross-encoder reranker is DISABLED
(``RERANKER_ENABLED=0``) because benchmarking on the Lyra corpus showed it
HURT precision (Recall@50 73.3% RRF-only vs Recall@5 33.3% with rerank).
The reranker code path remains available for re-enablement.
Args:
project_id: numeric string Jama project id (must be initialized first).
query: the ORIGINAL natural-language search query, verbatim. It is
always kept as the primary recall/rerank reference, so even
when `sub_queries` is supplied you MUST pass the original user
query here too.
sub_queries: RECOMMENDED. Rewrite `query` into 3-5 diverse search
sub-queries capturing different semantic angles
(synonyms, broader/narrower scope, related concepts) to
maximize recall for RRF fusion. Pass as a JSON array of
strings. The server normalizes them (forces `query` to the
front, de-duplicates, caps at 5). If omitted, the server
falls back to deterministic lexical variants.
Example for query "how does login timeout work":
["login session expiration",
"authentication timeout policy",
"user inactivity logout"]
item_type: optional Jama item-type id to filter (e.g. "89011" for Test
Cases, "89009" for Requirements). Pass None for all.
top_k: final results to return (default 50). The BEIR sweep showed
top_k=50 + candidate_k=100 is the optimal combination (highest
Recall@50 = 73.3%). Range 1-50; must be <= candidate_k.
candidate_k: candidate pool size after RRF fusion + item dedup
(default 100). A larger pool improves recall (vector+FTS
recall is capped by this): measured vecR@25=7%, @50=13%,
@100=21%, @200=34%. Note: candidate_k=200 DILUTES RRF
rankings and actually lowers Recall@50 to 64.4%, so 100
is the measured sweet spot. Range 1-500; must be >= top_k.
modified_after: optional ISO-8601 lower bound on item modified date
(inclusive). Naive timestamps are assumed UTC.
e.g. "2024-01-01" or "2024-06-01T00:00:00Z".
modified_before: optional ISO-8601 upper bound on item modified date
(inclusive). Naive timestamps are assumed UTC.
Returns:
{"project_id","query","sub_queries_used","results":
[{document_key,name,item_type_name,section,modified_date,text,
score,strategy}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No | ||
| item_type | No | ||
| project_id | Yes | ||
| candidate_k | No | ||
| sub_queries | No | ||
| modified_after | No | ||
| modified_before | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description details the full pipeline (Multi-Query expansion, hybrid recall, RRF fusion, item-level dedup, top_k results), explains why the reranker is disabled (benchmarking data), and covers parameter behavior, defaults, and constraints. This provides rich behavioral 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?
The description is well-structured with a summary, usage context, pipeline explanation, detailed Args, and return format. It is front-loaded with key information. However, it includes some extraneous detail (e.g., repeated benchmarking numbers) that could be trimmed without losing essential meaning.
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 (8 parameters, RAG pipeline, no output schema), the description is remarkably complete. It explains the return format, optimal settings, date handling, and provides an example for sub_queries. There are no significant gaps for an agent to 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?
The description includes a comprehensive Args section that explains every parameter in detail, including purpose, recommendations, examples (e.g., sub_queries), constraints (e.g., top_k ≤ candidate_k), and relationships between parameters. This fully compensates for the lack of schema descriptions.
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 it performs semantic search using high-precision RAG over an initialized Jama project. It explicitly distinguishes itself from native metadata queries ('Prefer it over native metadata unless the user gives an exact document key / status / item id'), making its purpose and differentiation from siblings 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?
The description provides explicit when-to-use and when-not-to-use guidance: it is the default tool for non-precise questions and should be preferred over native metadata unless the user has an exact identifier. It also explains the fusion strategy and recommends using sub_queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate all dependencies, configuration and storage.
Runs the offline pre-flight (packages + env vars + SQLite). When
``live=True`` it also probes the Jama OAuth token and the embedding
endpoint with a real request, so credentials can be verified without
running a full project init.
Args:
live: if True, perform live connectivity probes against Jama and the
embedding endpoint (slower; uses one Jama + one embedding call).
Returns:
{"blocking","issues":[...],"dependencies","config_issues","storage",
"live": {"jama","embedding"} | null, "hint"}
| Name | Required | Description | Default |
|---|---|---|---|
| live | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that live=True makes real requests to Jama and embedding endpoints, and notes it is slower. Without annotations, this provides adequate transparency about side effects and behavior. It could mention potential rate limits or that offline mode has no side effects.
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 well-structured with a brief summary followed by detailed Args/Returns. It is somewhat verbose but all sentences add value. Key information is 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?
The description covers both offline and live modes, explains return values, and provides context for credential verification. It lacks details on error handling or the specific checks performed, but is sufficient for a validation tool without an output 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?
The description thoroughly explains the 'live' parameter, including its effect (live connectivity probes), performance implications (slower, uses one call each), and purpose (verify credentials). This fully compensates for the 0% schema description coverage.
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 validates dependencies, configuration, and storage, with offline pre-flight and optional live probes. This uniquely distinguishes it from sibling tools like bootstrap_models or init_jama_project, which serve different purposes.
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 live=True (to verify credentials without full project init) and distinguishes offline from live modes. However, it does not explicitly state when not to use this tool or suggest alternatives for other validation needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tools have mostly distinct purposes. Pairings like query_jama_native_metadata vs query_jama_endpoint are clarified by descriptions, and get_sync_progress vs get_sync_status serve different monitoring needs. Only minor potential confusion between list_jama_project_relationships and get_jama_item_relationships.
Naming is somewhat inconsistent: some tools use verb_jama_noun (e.g., list_jama_projects) while others use verb_noun without jama (e.g., bootstrap_models). There are also variations like configure_jama and validate_setup. The pattern is not uniformly applied but remains readable.
23 tools is slightly high but well-scoped for a server that handles configuration, project initialization, lookup, detail retrieval, search, and monitoring. Each tool serves a distinct function, though some consolidation might be possible.
The tool set covers the lifecycle of retrieving Jama data: finding projects, initializing them, searching semantically or via metadata, and fetching details. Missing create/update/delete operations, but the server is read-only by design. Minor gaps like attachment download are not critical for the intended use case.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Versioned documentation registry and semantic search for AI tools and coding assistants.
Search your knowledge bases from any AI assistant using hybrid RAG.
Connect your AI to all your data - 200+ sources, intelligently filtered, compliance-ready.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/yyy188/jama-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
