Skip to main content
Glama
Jenkins MCP Server

Jenkins MCP Server

by TelmanH

Jenkins MCP Server

Read-only, multi-instance Jenkins access for AI assistants: VS Code GitHub Copilot (Agent mode) at work, Claude Code for local testing, or any other MCP client. Large build logs are analysed on the server; the model only receives small, relevant excerpts. A team knowledge base remembers solved problems, so the next analysis starts from what the team already knows.

Two ways to run it

Company use

Local testing / development

Who

everyone who analyses builds at work

developers of this server

Platform

Windows

macOS or Windows

AI client

VS Code GitHub Copilot (Agent mode)

Claude Code (macOS) or VS Code Copilot (Windows)

Jenkins

your company Jenkins

a test Jenkins in Docker (or any reachable one)

Setup

setup\windows\setup.ps1

tests/macos/setup.sh or setup\windows\setup.ps1 -Dev

Step-by-step guide

setup/windows/README.md

tests/README.md

Client config

.vscode/mcp.json, generated by setup.ps1 (token prompts, VS Code secure storage)

macOS: registered by the script (claude mcp add); Windows: .vscode/mcp.json

The server code is the same in both cases. Day-to-day usage: docs/USER_GUIDE.md.

Related MCP server: Debugging MCP Server

Read-only guarantee

The server cannot change anything in Jenkins:

  • Its HTTP session (ReadOnlySession in src/jenkins_mcp/client.py) refuses every method except GET and HEAD before a request leaves the process. A tool that tried to trigger, stop, delete or configure something would fail with "this MCP server is read-only".

  • Credentials are only sent to the configured Jenkins URLs; URLs of other hosts are refused.

  • Every tool that talks to Jenkins is marked readOnlyHint for the AI client. Only draft_kb_entry and propose_kb_update write: one new local file in knowledge/drafts/ each time (never overwrites, never Jenkins), so they are honestly marked as local writes.

  • The only other local writes are the log cache (~/.cache/jenkins-mcp, owner-only permissions).

  • Tested: offline (no non-GET request is ever sent, POST/PUT/PATCH/DELETE blocked) and live against a real Jenkins (all build numbers unchanged after running every tool).

Project layout

jenkins-mcp/
├── src/jenkins_mcp/        SERVER CODE (same on Windows and macOS, installed with pip)
├── config/                 YOUR SETTINGS: *.example templates committed; your yaml/.env are git-ignored
├── knowledge/              TEAM DATA: known issues (Markdown); may also live in its own repo
├── docs/USER_GUIDE.md      how to use it day to day
│
├── setup/windows/          COMPANY: Windows + VS Code Copilot
│   ├── setup.ps1           install script (-Dev: + test tools, for developers)
│   └── README.md           step-by-step guide
├── .vscode/                VS Code: mcp.json = Copilot server (generated, git-ignored; template mcp.example.json),
│                           settings.json = pytest
│
└── tests/                  LOCAL TESTING / DEVELOPMENT (never installed)
    ├── README.md           step-by-step guide: macOS + Claude Code, Windows + VS Code
    ├── macos/setup.sh      macOS: install + Claude Code registration + offline tests
    ├── test_*.py           offline tests (pytest, fake Jenkins)
    ├── fixtures/           sample log + example knowledge base for the tests
    └── live/               real Jenkins in Docker + live check of every tool (run_live.sh / run_live.ps1)

Source package:

src/jenkins_mcp/
├── app.py          FastMCP object, server instructions, shared parameter types
├── main.py         imports tools + prompts, run()  (command: jenkins-mcp)
├── vscode_config.py  writes .vscode/mcp.json (token prompts per instance), called by setup.ps1
├── xmlutil.py      Jenkins XML 1.1 parsing
├── settings.py     paths (JENKINS_MCP_HOME), env tunables
├── config.py       config/jenkins_instances.yaml + config/.env -> Settings, validation, instance lookup
├── client.py       ReadOnlySession (GET/HEAD only), Instance
├── targets.py      job/build/URL resolution
├── text.py         secret masking, output budget, formatting
├── rules/          built-in error/ignore/noise rules (YAML)
├── logs/           download + cache, cleaning, stage detection, error grouping
├── kb/             knowledge base: load entries, match against logs
├── tools/          MCP tools: instances, jobs, builds, logs, artifacts, infra, knowledge
└── prompts.py      analyse_build, document_session

Configuration

Files (templates in config/, your copies are git-ignored):

File

Content

config/jenkins_instances.yaml

Jenkins instances, TLS, log rules, knowledge base folder (template: jenkins_instances.example.yaml)

config/.env

Credentials, one pair per instance (template: .env.example)

Environment variables (set them in config/.env, in the MCP client config, or in the shell):

Variable

Default

Purpose

JENKINS_<NAME>_USER / JENKINS_<NAME>_TOKEN

-

Credentials of instance <name> (upper case, non-alphanumeric -> _). Other names: user_env / token_env in the yaml

JENKINS_MCP_HOME

nearest parent of the working dir with config/jenkins_instances(.example).yaml

Project folder with config/ and knowledge/

JENKINS_MCP_CONFIG

<home>/config/jenkins_instances.yaml

Instance file

JENKINS_MCP_KB_DIR

knowledge.dir in the yaml, else <home>/knowledge

Knowledge base folder (e.g. a private team repo)

JENKINS_MCP_CACHE_DIR

~/.cache/jenkins-mcp

Log cache (contains raw console logs)

JENKINS_MCP_CACHE_MAX_MB

1024

Cache size limit

JENKINS_MCP_MAX_LOG_MB

200

Larger logs keep the first 20 % and the end

JENKINS_MCP_MAX_CHARS

12000

Hard size limit of one tool answer

JENKINS_MCP_JOB_CACHE_S

60

Job lists (list_jobs, overviews) are reused for this long; 0 = off

JENKINS_MCP_LOG_LEVEL

WARNING

Server log level (stderr)

After editing the yaml or .env, call list_instances(reload_config=true); no restart is needed. Config problems are reported by list_instances under config_errors.

Use a dedicated Jenkins user with read permissions only (Overall/Read, Job/Read) for the API token. The server never writes to Jenkins, but a read-only account limits the damage if a token leaks.

Tools (34)

Tool

Purpose

list_instances

instances, token source, connection check (version, user/groups, admin rights, quiet-down), config errors, knowledge base state; reload_config

list_jobs

recursive job list with status/folder/name filter; failing jobs show the last green build

failures_overview

red/yellow jobs in the last N hours across all instances, with the last green build

recent_builds

every build in the last N hours across all instances: result, culprits, long-running builds

get_job

job details, permalinks, recent builds, parameters, children

find_jobs_by_scm

which jobs build a repository (or load a Shared Library), across instances; any URL spelling

get_build_summary

start here: result, params, agent, culprits, downstream builds, pending input, stages, failed stage, known issues, root-cause candidates, tail

get_stage_log

errors and tail of one stage (default: failed stage); exact = per-step log via wfapi (parallel branches)

get_pending_inputs

what a running build waits for (input step); approving stays in the UI

get_log_errors

de-duplicated error groups, annotated by the knowledge base

search_log / get_log_lines

regex search with context / line windows

get_test_failures

failed JUnit cases incl. how long they fail

get_pipeline_info

what actually ran: Jenkinsfile source, git checkouts, Shared Library versions (hint on LF-version mismatch), replay, slowest steps; show_script = executed Jenkinsfile

compare_builds

good vs bad: agent, params, stages, commits (Jenkinsfile/groovy changes flagged), new errors, errors also in good build, env.log diff; pick builds by node (good_on_node/bad_on_node) or take the good build from another instance (other_instance)

get_job_config

config.xml as a summary: SCM, Jenkinsfile path, parameters, triggers, retention, label, build steps, Config File Provider files, credential IDs; raw = masked XML

read_managed_file

content of a Config File Provider file (settings.xml...), secrets masked

get_job_config_history, diff_job_config

who changed the job config and when (Job Config History plugin); semantic + XML diff of two versions or against the live config

list_artifacts, read_artifact, get_env_log

artifact list (sizes, download URL), text artifacts (UTF-8, UTF-16, cp1252), secrets masked

compare_artifacts

artifacts of two builds: added/removed, changed (fingerprint, size, bytes); diff of one text artifact, checksum of a binary

list_workspace, read_workspace_file

files that were not archived, from the job / Pipeline node-block workspace (current state on the agent)

node_health, get_queue

agents (labels, disk, memory, offline reason, clock) and queue

get_node

one node: labels, which build runs on which executor, Java version, config.xml (remote root, launcher, node env vars masked, tool locations)

find_known_issues

match a build or a pasted error text against the knowledge base

get_known_issue, list_known_issues

read / list entries, with how often each matched since the server started

draft_kb_entry

write a new local draft in knowledge/drafts/ (local write, never Jenkins)

propose_kb_update

propose an update of an existing entry (new build, extra regexes) as a new draft next to it (local write)

recurring_errors

errors across the newest builds of a job: regression ("new since #N") vs. also in green builds

Prompts: analyse_build, document_session, morning_report (Copilot: type / and pick mcp.jenkins...; Claude Code: /mcp__jenkins__analyse_build).

All tools are read-only towards Jenkins; see Read-only guarantee.

Knowledge base workflow

  1. Analyse a build. get_build_summary shows known_issues if an entry matches.

  2. When the cause is found and confirmed, run the prompt document_session (or ask the agent). It checks for duplicates and calls draft_kb_entry, or propose_kb_update when an entry already exists. recurring_errors finds red-herring candidates (errors that also occur in green builds).

  3. Review the draft in knowledge/drafts/, move it to knowledge/, commit it to your team's private knowledge repo. The server picks up file changes automatically.

Company knowledge does not belong in this public repository: .gitignore excludes knowledge/KB-*.md and drafts. Keep entries in a private repo and point JENKINS_MCP_KB_DIR (or knowledge.dir) at its checkout.

Format and field reference: knowledge/README.md. Start new entries from knowledge/TEMPLATE.md.

Development

See tests/README.md. Adding a tool: write a function with @mcp.tool(annotations=READ_ONLY) in a module under src/jenkins_mcp/tools/ (for a new module also import it in tools/__init__.py), and add a test to tests/test_tools.py.

Notes and limits

  • Multibranch branch names containing / are addressed with %2F (as list_jobs shows them).

  • Stage line ranges come from console markers; output of parallel branches can interleave (get_stage_log exact=true reads the stage step by step from wfapi instead).

  • Builds still running are not cached on disk; their log is fetched incrementally (only the new part).

  • Downstream builds are recognised from the console line Starting building: <display name> #N. If a job has a custom display name, it cannot be resolved by that name, and the summary says so.

  • Logs larger than JENKINS_MCP_MAX_LOG_MB keep the first 20 % and the end.

  • Log content is untrusted: a log line can contain text that looks like an instruction. The server cannot change Jenkins, so such text cannot trigger actions through it.

Security

See SECURITY.md for the threat model and how to report a vulnerability.

License

MIT © 2026 Telman Huseynli

Roadmap

  • Release 1.1.0: the live Docker test (Jenkins 2.580.1) and a manual Windows / VS Code Copilot run against real instances passed. Set the package status back to 5 - Production/Stable, turn Unreleased in CHANGELOG.md into 1.1.0, tag v1.1.0 and publish a GitHub release.

  • Replace the module-level singletons (config, knowledge base cache, log LRU, job tree cache) with one application context object, and pass log rules into logs/ instead of reading the global config there.

  • CI pipeline on Windows: ruff, mypy, pytest.

  • Read-only plugin tools: installed plugins and versions, plugins with problems (missing dependencies), available updates. /pluginManager/api/json?depth=1 usually needs Overall/SystemRead or Administer: check it with a normal user's token first; without that permission the tools would only return 403.

  • More read tools: views, node env/PATH (system info, needs admin), Jenkinsfile and JCasC history from Git (Bitbucket).

  • Optional HTTP transport for one shared team server (needs authentication / a gateway).

  • Human-in-the-loop write actions (not implemented): plan_* tool -> one-time token -> human confirms -> execute_plan with a separate service account and an allow-list.

Available Tools

34 tools
compare_artifactsCompare ArtifactsA
Read-onlyIdempotent

Compare the archived artifacts of two builds. Without path: artifacts only in one build, and which common ones changed (by Jenkins fingerprint, else by size, small files byte-wise). With path: a unified diff of a text artifact (secrets masked), or the sha256/size of a binary one.

NameRequiredDescriptionDefault
badNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.lastFailedBuild
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
goodNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.lastSuccessfulBuild
pathNoOne artifact to diff; empty = compare the lists
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description adds real behavioral detail beyond that — change detection via Jenkins fingerprints, fallback to size, byte-wise comparison for small files, and secret masking in text diffs. It doesn't cover failure behavior when a path is absent in one or both builds, which is the main remaining gap.

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

Conciseness4/5

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

Two compact sentences, front-loaded with the core action and then partitioned by mode; no filler. The parenthetical comparison logic ('by Jenkins fingerprint, else by size, small files byte-wise') is dense but each clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations carrying safety and an output schema carrying return shape, the description covers what remains: both modes, match/change algorithm, and secret masking. Only edge cases (missing artifact, non-text/non-binary content) are left unstated.

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

Parameters3/5

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

Schema coverage is 100% and the permalink enums for bad/good plus instance/path are fully documented in the schema, so the baseline of 3 applies. The description reinforces what 'path' empty vs. set means but adds no syntax or format detail beyond the schema (e.g., exact artifact path format, leading-slash rules).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Compare the archived artifacts of two builds') and immediately splits the behavior into its two modes, so an agent knows exactly what it produces. It does not explicitly name compare_builds or list_artifacts to draw the boundary, but the scoping to 'archived artifacts' is specific enough to separate it by name and subject.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

The 'Without path' / 'With path' construction gives clear mode-selection guidance: omit path to get a membership/change summary, supply path to get a content diff or hash. It stops short of stating when to prefer this over compare_builds or read_artifact, so no explicit exclusions or alternatives are given.

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

compare_buildsCompare BuildsA
Read-onlyIdempotent

What changed between a good and a bad build: result, duration, agent node, parameters, stage status/durations, commits in between (pipeline_changes = commits touching a Jenkinsfile or *.groovy), error groups that are new in the bad build, and env.log differences (if both builds archived env.log). Ideal for 'it worked yesterday', 'why is node A slower than node B' and for checking whether an error also occurs in green builds. good_on_node / bad_on_node pick builds by agent ('works on agent-01, fails on agent-03'; Pipeline jobs need up to 10 log reads); other_instance compares the same job across instances (no commit range).

NameRequiredDescriptionDefault
badNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.lastFailedBuild
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
goodNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.lastSuccessfulBuild
instanceNoJenkins instance name from list_instances. Empty = default instance.
bad_on_nodeNoPick the newest failed/unstable build that ran on this node (overrides bad)
good_on_nodeNoPick the newest successful build that ran on this node (overrides good)
other_instanceNoTake the GOOD build of the same job from this instance (cross-instance comparison)

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/openWorld, yet the description still adds real behavior: env.log comparison only happens 'if both builds archived env.log', and Pipeline jobs using node selection may need 'up to 10 log reads', which signals cost. It also notes other_instance yields no commit range. A minor gap remains on output shape, though an output schema exists.

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

Conciseness4/5

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

Front-loaded with the core comparison, then use cases, then parameter caveats — a sensible order with no filler sentences. It is dense and slightly run-on due to stacked parentheticals, but each clause conveys information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter comparison tool with full schema coverage, annotations for safety, and an output schema, the description covers purpose, alternatives, per-parameter intent, and known costs/caveats. Nothing an agent needs to invoke it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond it: it explains the intent of good_on_node/bad_on_node ('works on agent-01, fails on agent-03'), clarifies that pipeline_changes means commits touching a Jenkinsfile or *.groovy, and warns other_instance excludes the commit range. That is meaningful value on top of the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific diff statement ('What changed between a good and a bad build') and enumerates the exact dimensions compared: result, duration, node, parameters, stage status, commits, new error groups, env.log. It is clearly a build-diff tool and is distinguishable from siblings like compare_artifacts and diff_job_config.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Names concrete scenarios ('it worked yesterday', 'why is node A slower than node B', checking whether an error also occurs in green builds) and explains the routing logic for the selector parameters (good_on_node/bad_on_node for per-agent comparisons, other_instance for cross-instance with the caveat 'no commit range'). This is explicit when-to-use guidance, not inferred.

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

diff_job_configDiff Job ConfigA
Read-onlyIdempotent

What changed between two configuration versions of a job: a semantic list ('triggers: cron: H 3 * * * -> cron: H 2 * * *', parameters, SCM, script path, retention...) plus a unified diff of the XML. Secrets are masked in both. Default: the newest version against the one before it.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
newerNoTimestamp, or 'current' for the live config.xml; empty = the newest version
olderNoTimestamp from get_job_config_history; empty = the version before `newer`
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description adds real value with the secrets-masking guarantee and the output shape (semantic change list + unified XML diff). It does not discuss large-diff handling or failure modes when a version is missing, which keeps it from a 5.

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

Conciseness5/5

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

Two tight sentences: output content first, masking and default behavior second. No filler, and the most decision-relevant facts are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and full parameter coverage, the description needn't detail return values, and it correctly covers masking and default selection. A note on behavior when history is empty or a version is not found would make it complete.

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

Parameters3/5

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

Schema description coverage is 100%, so baseline is 3. The description restates the default comparison (newest vs previous) that the schema's `newer`/`older` defaults already encode, adding little beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (diff) and resource (job configuration versions) and enumerates what the diff contains (triggers, parameters, SCM, script path, retention, plus unified XML diff). An agent can distinguish it from get_job_config and get_job_config_history directly from the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Explains the default comparison behavior (newest vs the one before) and implicitly routes to get_job_config_history by naming it as the source of the `older` timestamp. Missing an explicit 'use this instead of X' statement for the single-config siblings, but usage context is clear.

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

draft_kb_entryDraft Kb EntryA

Write a NEW knowledge base draft (Markdown) to knowledge/drafts/ for human review. Call this at the end of a debugging session once the user confirmed the root cause. It never touches Jenkins and never overwrites a file. Drafts are not used for matching until a human reviews them and moves them into knowledge/ (then commit to Git).

NameRequiredDescriptionDefault
jobNoJob full name or Jenkins URL. Empty = not tied to a build.
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
matchYesPython regexes (case-insensitive). Use specific phrases copied from the log, not generic words like 'ERROR'.
stageNo
titleYesShort title: symptom -> cause
statusNoopen | solved | workaroundopen
versionNoProduct/application version of the build, if relevant
categoryNo
instanceNoJenkins instance name from list_instances. Empty = default instance.
solutionNoHow it was / is fixed. Empty if not known yet.
symptomsNo
how_foundNoHow the cause was identified (searches, comparisons)
root_causeYesThe confirmed root cause
consequencesNoRegexes of follow-up errors caused by this issue
red_herringsNoRegexes of errors that appeared but were NOT the cause (e.g. also present in green builds)

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

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

Adds real context beyond the annotations: the write target, that Jenkins is untouched, that no existing file is overwritten, and that drafts stay inert until a human reviews and commits them. The gap is the idempotentHint=false signal — the description never says what happens when a draft with the same title already exists, so duplicate behavior remains unexplained.

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

Conciseness5/5

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

Four short sentences, each carrying distinct information: what is written and where, when to call it, safety guarantees, and lifecycle. Front-loaded with the action, zero filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter write tool with annotations and an output schema, the description covers purpose, timing, safety and downstream lifecycle well. The remaining shortfall is duplicate-title behavior and any hint about how the drafted match/symptom regexes will be consumed later.

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

Parameters3/5

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

Schema description coverage is 80%, so the schema already documents most of the 15 parameters (match, consequences, red_herrings, status, etc.). The description contributes nothing parameter-specific — notably no guidance on how 'match' regexes relate to the draft's future matching role — so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Write), resource (a NEW knowledge base draft in Markdown) and destination (knowledge/drafts/). The word 'NEW' plus 'never overwrites a file' implicitly separates it from the sibling update path (propose_kb_update) and from anything that would modify knowledge/ directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Gives an explicit trigger point: 'at the end of a debugging session once the user confirmed the root cause,' which is a concrete pre-condition an agent can check. It does not name propose_kb_update or state when to prefer it, so the exclusion side of the decision is left implicit.

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

failures_overviewFailures OverviewA
Read-onlyIdempotent

Jobs whose LAST build failed (and optionally is unstable) within the last hours, across one or all instances in parallel. Good for a morning check or 'what is red right now'.

NameRequiredDescriptionDefault
hoursNo
folderNo
instanceNoInstance name or 'all'all
include_unstableNo
limit_per_instanceNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context about last-build semantics, optional unstable inclusion, and parallel querying across instances, but it does not explain limits, pagination, or result shape.

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

Conciseness5/5

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

The description is two compact sentences with no wasted language. The core filtering behavior is front-loaded before the usage example.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. However, with five parameters and only 20% schema description coverage, the description is not complete enough to fully explain `folder` and `limit_per_instance` behavior for an overview tool.

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

Parameters3/5

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

Schema description coverage is low at 20%, so the description should compensate more. It clarifies `hours`, `include_unstable`, and `instance` ("one or all instances"), but it omits meaning for `folder` and `limit_per_instance`, leaving two of five parameters undocumented beyond type and default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and filter: jobs whose LAST build failed within the last `hours`, optionally including unstable jobs, across one or all instances. This is clear and actionable, though it does not explicitly distinguish the tool from siblings such as recent_builds or list_jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

It gives clear usage context with "Good for a morning check or 'what is red right now'," which tells the agent when this overview is appropriate. It does not explicitly state when not to use it or name alternative tools for narrower queries.

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

find_jobs_by_scmFind Jobs By ScmA
Read-onlyIdempotent

Jobs whose last build checked out a repository (app repo or Shared Library), across instances: 'job | STATUS #n | repo URL'. URL spellings are normalized (https / ssh / port / Bitbucket /scm/ / .git). ~1 request per instance. Jobs that were never built cannot be found this way.

NameRequiredDescriptionDefault
urlYesRepository URL in any spelling (https, ssh, with .git) or a part of it like 'org/repo'
folderNo
instanceNoInstance name or 'all'all

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds real behavioral context beyond them: URL normalization across https/ssh/port/Bitbucket /scm/ / .git spellings, a cost signal ('~1 request per instance'), and the never-built limitation. These are exactly the traits an agent needs to predict results and cost.

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

Conciseness4/5

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

Three compact sentences with the core definition first, then output shape, then caveat. Slightly telegraphic ('across instances:' fragment) but no sentence is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description supplies the remaining essentials: result format, normalization behavior, request cost, and a key negative constraint. Only the undocumented 'folder' parameter leaves a small gap.

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

Parameters4/5

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

Schema coverage is 67%, with url and instance documented in the schema. The description adds meaning the schema lacks: the URL is normalized across spellings, so partial forms ('org/repo') behave predictably, and 'across instances' clarifies the semantics of instance='all'. The 'folder' parameter remains unaddressed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource (jobs whose last build checked out a repository) and adds scope qualifiers ('app repo or Shared Library', 'across instances') that clearly differentiate it from sibling list_jobs/get_job. An agent can pick this tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

The description implies the use case (locate jobs by repository URL) and gives an explicit exclusion: 'Jobs that were never built cannot be found this way.' It stops short of naming the alternative tool (list_jobs) for jobs without builds, so it is strong but not fully prescriptive.

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

find_known_issuesFind Known IssuesA
Read-onlyIdempotent

Look up the team knowledge base. With job (+build) the build log is matched against every entry in scope (instance/job); with text, a pasted error message is matched. Returns matching entries with the first matching log line and the documented fix. get_build_summary already does this automatically - use this tool for a pasted error or before writing a new entry.

NameRequiredDescriptionDefault
jobNoJob full name or Jenkins URL. Empty = not tied to a build.
textNoError text to look up instead of a build
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
instanceNoJenkins instance name from list_instances. Empty = default instance.
include_draftsNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

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

With readOnlyHint/idempotentHint already declaring a safe read, the description adds real behavior: matching happens against 'every entry in scope (instance/job)' and returns the first matching log line plus the documented fix. It does not mention how include_drafts changes results or any pagination/result-limit behavior, which is the main remaining gap.

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

Conciseness5/5

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

Four sentences, zero filler, front-loaded with the purpose before the mode split and the sibling routing note. Every sentence carries information the agent needs to call it correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description's extra note about return contents is bonus rather than required. Matching modes, scoping, and routing are all covered; only the include_drafts flag and any result-size limits are left unexplained.

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

Parameters4/5

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

Schema coverage is 80%, so the bar is already low, but the description still adds value by explaining the interaction of job+build versus text as alternate matching modes. The one fully undocumented parameter (include_drafts) gets no explanation in either schema or description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Look up the team knowledge base') and then spells out the two distinct matching modes: build-log matching with job (+build), and error-text matching with text. An agent can distinguish it from list_known_issues, get_known_issue, and get_build_summary without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Explicitly names when to use it ('for a pasted error or before writing a new entry') and explicitly names the overlapping sibling ('get_build_summary already does this automatically'), so the agent knows this tool is for the non-automatic cases. When-to-use and alternative routing are both present.

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

get_build_summaryGet Build SummaryA
Read-onlyIdempotent

START HERE for any build question. Compact summary of one build: result, duration, trigger, parameters, agent node, commits, culprits (failed builds), downstream builds started by the build step (with their result), pending input steps (running builds), stages (with failed stage and its error), test counts, log size, known issues from the team knowledge base, likely root-cause error lines with line numbers, and the last meaningful log lines. Typical size: 1-3k tokens even for 30k+ line logs.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnly/openWorld/idempotent, so the burden is lower; the description still adds genuinely useful behavior: the compact output envelope (~1-3k tokens even for 30k+ line logs) and the fact that only "last meaningful log lines" are included. It does not cover edge cases such as a still-running or non-existent build, so it is strong but not exhaustive.

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

Conciseness4/5

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

The directive is front-loaded and the enumerated field list is dense but each item conveys a distinct capability rather than filler. It is longer than strictly necessary for a single tool but earns most of its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return shapes, and annotations cover the safety profile; the params are fully documented. What remains unaddressed is failure behavior (unknown job/build, in-progress builds), which would matter for an openWorld tool.

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

Parameters3/5

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

Schema description coverage is 100%, with job, build (including permalink enum-like values), and instance all documented in the schema. The description adds no syntax, format, or fallback details beyond saying the tool summarizes "one build." Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a scope directive ("START HERE for any build question") and then enumerates exactly what the summary returns: result, duration, trigger, commits, culprits, downstream builds, pending inputs, stages, tests, log errors. This is a specific verb+resource with contents spelled out, clearly distinguishing it from narrower siblings like get_log_lines, get_test_failures, and compare_builds.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

"START HERE for any build question" gives clear entry-point guidance that positions it ahead of the drill-down siblings, and the size note explains why it is the cheap first call. It does not explicitly name when to skip it in favor of a sibling (e.g., full log retrieval), so it stops short of a full when/when-not statement.

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

get_env_logGet Env LogA
Read-onlyIdempotent

The env.log artifact (environment variables dumped by the pipeline) of a build, with secret-looking values masked. Optional regex pattern filters the lines (e.g. 'JAVA|MAVEN|NODE').

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
patternNo
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, and open-world behavior, so the bar is lower, and the description clears it by disclosing that secret-looking values are masked — a material behavioral fact that changes how an agent should interpret the output. It stops short of covering truncation or what happens when a build has no env.log.

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

Conciseness5/5

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

Two tight sentences: the identity of the artifact and its masking behavior come first, then the optional filter with an example. No filler, nothing repeated from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return-value explanation is unnecessary, and the description covers the artifact's nature, redaction, and the filtering option. Gaps are minor: no mention of truncation on very large logs or error behavior when the artifact is absent.

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

Parameters4/5

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

Schema coverage is 75%, with job, build, and instance documented in the schema; the one gap, `pattern`, is exactly what the description fills, explaining that it is an optional regex line filter and giving a concrete example ('JAVA|MAVEN|NODE'). This is meaningful semantics beyond the bare empty-string default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource precisely: the env.log artifact of a build, including its provenance (variables dumped by the pipeline) and a key transformation (secret-looking values masked). It does not, however, distinguish itself from siblings like read_artifact or get_log_lines, which could plausibly also surface this content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage is only implied — read this when you need a build's environment variables. There is no explicit 'use this instead of read_artifact when...' or any statement about when the tool is not appropriate, despite several sibling tools that read build files and logs.

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

get_jobGet JobA
Read-onlyIdempotent

Job details: type, health, permalinks (last/lastFailed/lastSuccessful build numbers), recent builds, parameters it accepts, and children if it is a folder/multibranch project.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
instanceNoJenkins instance name from list_instances. Empty = default instance.
recent_buildsNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds useful scope context (children are returned only for folder/multibranch jobs), but says nothing about permission requirements, instance resolution behavior, or whether the call is expensive on large jobs.

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

Conciseness5/5

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

A single front-loaded sentence with no filler, and every clause maps to something the tool actually returns. Nothing is repeated from the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description does not owe the agent return-value structure, and annotations cover the read-only profile. What is still missing is routing guidance against the many near-neighbors (get_job_config, get_build_summary, get_pipeline_info) and any explanation of the undocumented recent_builds count.

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

Parameters3/5

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

Schema coverage is 67%: 'job' and 'instance' are well documented in the schema, while 'recent_builds' has no schema description at all. The description's phrase 'recent builds' gestures at that parameter but never states that it is a count, its default, or its upper bound, so the uncovered parameter stays underspecified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (job details) and enumerates exactly what is returned: type, health, permalinks, recent builds, accepted parameters, and children for folder/multibranch jobs. That enumeration implicitly separates it from list_jobs (listing) and get_job_config (configuration), but no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage is implied rather than stated: an agent can infer 'call this to inspect one job' from the field list, and the children note hints at folder/multibranch traversal. There is no explicit when-to-use, when-not-to-use, or named alternative such as get_job_config or get_build_summary.

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

get_job_configGet Job ConfigA
Read-onlyIdempotent

A job's (or folder's) configuration from config.xml as a compact summary: type, SCM repo/branches, Jenkinsfile path or inline script, parameters, triggers (cron, SCM polling, upstream), build retention, concurrency, label, freestyle build steps, Config File Provider files (managed_files), folder Shared Libraries and the credential IDs used (IDs only, never values). Needs Job/ExtendedRead. Jobs managed by JCasC/JobDSL: this is the live state; the source of truth is in Git.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
rawNoReturn the whole config.xml (masked, size-limited) instead of the summary
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description focuses on additional context: required permissions, data freshness for managed jobs, and security (credential IDs only, never values). It does not contradict annotations and adds meaningful behavioral traits beyond them.

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

Conciseness4/5

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

The description is front-loaded with the core purpose, then permission needs and a caveat. The field enumeration is dense but necessary to convey what the summary contains. There is no filler, though the first sentence is quite long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the presence of an output schema, the description still adds valuable context: permissions, data freshness for managed jobs, and security constraints. It stops short of mentioning alternatives, but that is more properly a usage guideline concern. Overall, it provides enough for an agent to use the tool correctly.

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

Parameters3/5

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

Schema coverage is 100% and all three parameters have detailed descriptions, so the baseline is 3. The description adds value by specifying what the default summary includes (type, SCM, triggers, etc.), which clarifies the difference between raw=false and raw=true. However, it does not add syntax or format details for the job or instance parameters beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the specific resource (job/folder configuration from config.xml) and enumerates what the compact summary contains, making the purpose clear. However, it does not differentiate from siblings such as get_job, get_job_config_history, or diff_job_config, so an agent must infer that this is the tool for retrieving current config rather than comparing or listing jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

The description provides a permission prerequisite (Needs Job/ExtendedRead) and notes that JCasC/JobDSL jobs have their source of truth in Git, which is a useful caveat. Yet it never explicitly states when to use this tool instead of alternatives like diff_job_config or get_job, leaving usage to inference.

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

get_job_config_historyGet Job Config HistoryA
Read-onlyIdempotent

Who changed a job's configuration and when (Job Config History plugin), newest first: 'timestamp | operation | user'. Use the timestamps with diff_job_config. Changes by SYSTEM usually come from JCasC / JobDSL seed jobs: then the source of truth is Git and UI changes get overwritten.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
limitNo
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/openWorld safety, and the description adds real context beyond them: ordering guarantee, the record format, the plugin dependency, and the operationally important caveat that JCasC/JobDSL changes are authoritative in Git and UI edits get overwritten. It stops short of saying what happens with no history or a missing plugin.

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

Conciseness5/5

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

Three compact sentences, front-loaded with the core question and output shape before the follow-up-tool hint and the caveat. Every sentence carries actionable information with no restatement of the name or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description doesn't need to explain return values, and it covers purpose, ordering, follow-up, and the main operational gotcha. Only minor gaps remain (behavior on missing plugin, empty history, and how 'limit' truncates).

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

Parameters3/5

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

Schema coverage is 67%: 'job' and 'instance' are documented in-schema, but 'limit' has only a default of 20 with no explanation of ordering/truncation semantics. The description adds nothing about parameters, so the baseline 3 for partial schema coverage applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Who changed a job's configuration and when') and pins the implementation to the Job Config History plugin. The return shape 'timestamp | operation | user' plus 'newest first' makes it immediately distinguishable from get_job_config (current state) and diff_job_config (content diff).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Gives an explicit pairing rule — 'Use the timestamps with diff_job_config' — so the agent knows the follow-up call. It also explains the SYSTEM-user case and the JCasC/JobDSL consequence. It doesn't explicitly state when NOT to call it (e.g., 'for current config use get_job_config'), which keeps it off a 5.

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

get_known_issueGet Known IssueA
Read-onlyIdempotent

Full text of one knowledge base entry: scope, symptoms, root cause, fix, how it was found, red herrings. Content is written by the team (reviewed) - drafts are marked as unreviewed.

NameRequiredDescriptionDefault
idYesEntry id like KB-0001 (drafts too)

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely new context: the entry is team-written and reviewed, and drafts are flagged as unreviewed, which tells the agent how much to trust the content. It stops short of stating error behavior for missing ids or whether drafts are returned by default.

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

Conciseness4/5

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

Two short sentences, front-loaded with what the tool returns and followed by the trust/review caveat. Dense and waste-free, though the fragment-style field list is slightly terse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return structure need not be described, and the description covers the content shape plus the reviewed/unreviewed nuance. For a single-parameter read tool this is close to sufficient; only error handling for invalid ids is unaddressed.

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

Parameters3/5

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

Schema coverage is 100% and the id format (KB-0001) is already documented in the schema. The description's only added signal is 'drafts too', which restates what the schema says. Baseline 3 is appropriate when the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States precisely that it returns the full text of a single knowledge base entry and enumerates the fields it contains (scope, symptoms, root cause, fix, discovery, red herrings). The singular 'one entry' implicitly contrasts with the list/find siblings, but no sibling is named, so the differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage is only implied: 'one knowledge base entry' plus the required id parameter suggests 'use when you already have an entry id'. There is no explicit statement of when to prefer this over find_known_issues or list_known_issues, and no guidance on what to do if the id is unknown.

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

get_log_errorsGet Log ErrorsA
Read-onlyIdempotent

All detected error lines of a build, de-duplicated into groups (same message = one group with a count), in order of first appearance, with line number, stage, severity and a shortened stack trace. Severity 'warn' = error text inside a line logged as WARN (often retries, rarely the cause); category 'generic' = an 'Error:'/'FATAL:' line no specific rule knows (ranked after specific errors). Groups the knowledge base knows are annotated ('known issue', 'known noise', 'consequence of'). Generic Jenkins wrapper messages ('script returned exit code 1') are hidden unless include_generic.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
categoryNoOptional filter: maven, tests, java, helm, k8s, ansible, docker, network, nexus, system, jenkins, generic or a custom category
instanceNoJenkins instance name from list_instances. Empty = default instance.
max_groupsNo
include_genericNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior5/5

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

Annotations only declare readOnly/idempotent/openWorld, but the description adds substantial behavior: de-duplication into groups with counts, ordering by first appearance, ranking of generic errors after specific ones, KB annotation of known groups, and hiding of generic Jenkins wrapper messages unless include_generic. That is exactly the kind of output-shaping behavior an agent cannot get from structured fields.

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

Conciseness4/5

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

Front-loaded with the core definition, and every subsequent clause carries real semantic load (severity, category, KB tags, hiding rule). It is dense and semicolon-heavy, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return-value explanation is unnecessary, and the description still covers filtering, defaults and grouping behavior. The one meaningful gap is max_groups — whether it truncates, and how truncation is reported — for a 6-parameter tool.

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

Parameters4/5

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

Schema coverage is 67%, and the description compensates where the schema is thin: it defines the 'generic' category and its ranking, and explains include_generic's hiding behavior, both of which are undocumented in the schema. max_groups is left entirely unexplained, which keeps it below 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'all detected error lines of a build, de-duplicated into groups' — plus ordering, grouping and payload contents. It is clearly distinguishable from siblings like get_log_lines (raw lines) and recurring_errors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage is implied rather than stated: the severity/category semantics and the include_generic toggle imply 'use this for error triage, not raw log reading', but no sibling or alternative is named and no when-not condition is given. Guidance exists only as implicit rules inside the field semantics.

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

get_log_linesGet Log LinesC
Read-onlyIdempotent

A window of the cleaned console log with line numbers (max 400 lines per call). Use line numbers from the other tools. hide_noise drops [Pipeline]/download/progress lines.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
countNo
startNo1-based first line; 0 or negative = tail of the log
instanceNoJenkins instance name from list_instances. Empty = default instance.
hide_noiseNo

Output Schema

NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds real behavioral context — a hard 400-line cap and what hide_noise filters out — but leaves "cleaned" undefined and does not say what happens if count exceeds 400 or if the requested range runs past the log end.

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

Conciseness3/5

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

Two short sentences with no filler, so nothing is wasted. But the first sentence is a fragment that front-loads a noun phrase instead of the action, which weakens orientation for an agent skimming definitions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and strong annotations, the description only needs to cover paging behavior and the noise filter, and it does both. The remaining gap — how this differs from sibling log tools — is a routing concern more than a completeness one.

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

Parameters3/5

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

Schema coverage is 67%; job, build, start, and instance are already documented in the schema, so the burden is small. The description compensates for the two undocumented parameters by giving hide_noise meaning and tying the 400-line cap to count, but it adds no syntax detail for count or paging beyond that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource (the cleaned console log) and its key output trait (line numbers, 400-line window), but it is a noun phrase with no verb — it never says "retrieves" or "returns a slice of". It also does not distinguish this tool from close siblings like get_stage_log, search_log, or get_log_errors, which also surface log content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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

"Use line numbers from the other tools" implies a follow-up workflow after search_log/get_log_errors, which is a useful hint. However, there is no explicit when-to-use guidance and no exclusion: nothing says when to prefer get_stage_log, search_log, or get_env_log instead of pulling a raw window.

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

get_nodeGet NodeA
Read-onlyIdempotent

One node in detail. Live: online/offline (reason), labels, every executor with the build running on it, Java version (if a monitor exposes it), disk/memory/clock. Configuration (config.xml): remote root, mode (any job / matching labels only), launch method (e.g. SSH host), node environment variables (secrets masked) and tool locations. Without Computer/ExtendedRead permission only the live part is shown.

NameRequiredDescriptionDefault
nameYesNode name as shown by node_health; a unique part is enough, 'built-in' = the controller
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent and open-world traits, so the bar is lower; the description still earns credit for disclosing permission-gated behavior (without Computer/ExtendedRead only the live part is shown) and secret masking in environment variables. It does not say what happens when a node name is unknown, which keeps it off a 5.

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

Conciseness4/5

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

The content is dense but front-loaded, with the two data groups (live vs config.xml) separated cleanly. The telegraphic inventory style is efficient, though slightly list-like rather than prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations and an output schema already present, the description covers the remaining gaps an agent needs: what sections exist, that some fields are permission-gated, and that secrets are masked. Nothing essential for correct invocation is missing.

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

Parameters3/5

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

Schema coverage is 100% and both parameters are well documented in the schema, including the 'unique part is enough' and 'built-in' semantics. The description adds nothing parameter-specific, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific resource and scope ('One node in detail') and then enumerates exactly what is returned: live status, labels, executors, Java version, disk/memory/clock, plus config.xml settings. That enumeration distinguishes it from node_health implicitly, though it never names the sibling directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage is only implied through 'in detail' versus the health-oriented sibling; the schema's 'name' parameter points at node_health as the source of names, but the description itself states no explicit when-to-use or when-not rule.

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

get_pending_inputsGet Pending InputsA
Read-onlyIdempotent

What a running Pipeline build is waiting for (input steps): message, id, button, requested inputs and who may approve. Read only - approving or aborting stays a human action in the Jenkins UI.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, so the description earns credit for going further: it explicitly bounds the tool's authority ('approving or aborting stays a human action in the Jenkins UI'), which stops an agent from trying to resolve the input through this tool. It does not mention what happens when no input is pending.

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

Conciseness5/5

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

Two sentences, no filler. The resource definition is front-loaded and the read-only boundary closes it, with every clause carrying information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description need not explain return values, and it names the returned fields anyway. The only real gap is the caller-side precondition (which build is in scope, what an empty result means), which leaves it just short of complete.

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

Parameters3/5

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

Schema description coverage is 100%, so job/build/instance semantics (folders, permalinks, instance inference from URL) are fully documented in the schema. The description adds nothing about parameters, which is the correct baseline when the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States precisely what is returned: the pending `input` steps of a running Pipeline build, enumerating the payload (message, id, button, requested inputs, approvers). No sibling tool covers pending input steps, and the phrasing makes that scope obvious without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage is only implied — an agent can infer this is for a build blocked on input, but there is no explicit when-to-use, no prerequisite (e.g. needing a build number or that the build must be running), and no named alternative among siblings such as get_pipeline_info or get_queue.

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

get_pipeline_infoGet Pipeline InfoA
Read-onlyIdempotent

What actually ran in a Pipeline build: where the Jenkinsfile came from, the git checkouts (repo, branch, commit), the Shared Library versions that were loaded (with a hint when a library branch does not match a VERSION parameter, e.g. rel-2.3 vs REL_VERSION=2.4), replay / restart-from-stage, and the slowest steps, and the Config File Provider files it provisioned. show_script=True adds the executed script (needs the Run/Replay permission).

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
instanceNoJenkins instance name from list_instances. Empty = default instance.
show_scriptNoAlso return the Jenkinsfile that actually ran (from the replay page)

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/openWorld, so safety is covered. The description adds genuinely useful context beyond them: that show_script reads the replay page and requires the Run/Replay permission, and that library-version output flags branch/VERSION mismatches. It does not discuss cost, latency, or failure modes for missing builds, hence not a 5.

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

Conciseness4/5

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

Purpose is front-loaded and the dense enumeration of returned sections is information-bearing rather than filler. The single long sentence chains clauses with repeated 'and', which slightly hurts readability, but nothing is truly redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only introspection tool with a full output schema and 100% parameter coverage, the description supplies what structured fields cannot: what sections come back, the permission caveat for show_script, and the mismatch-hint behavior. Nothing needed to invoke it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline would be 3, but the description adds semantics the schema lacks — notably that show_script requires the Run/Replay permission and pulls from the replay page. The other parameters (job, build, instance) are left entirely to the schema, which is acceptable given full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific framing — 'What actually ran in a Pipeline build' — then enumerates concrete artifacts: Jenkinsfile provenance, git checkouts, shared library versions, replay/restart-from-stage, slowest steps, Config File Provider files. That is far more specific than a generic build-info tool. It never names a sibling (e.g., get_build_summary or get_job_config) to delineate scope, which keeps it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage is only implied by the content list: an agent can infer this is the tool for pipeline internals rather than job config or logs. There is no explicit when-to-use statement, no exclusions, and no pointer to alternatives among the many build/artifact siblings. The one conditional given (show_script=True) is a parameter note, not usage routing.

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

get_queueGet QueueA
Read-onlyIdempotent

Build queue: what is waiting, for how long, and why (e.g. 'Waiting for next available executor on label X'). Stuck items are flagged. Useful when builds 'hang' before starting.

NameRequiredDescriptionDefault
limitNo
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already cover the read-only/idempotent safety profile, and the description adds genuine context beyond them: wait reasons with example text, stuck-item flagging, and the hang-diagnosis framing. It does not mention instance scoping or result-size behavior, so not a 5.

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

Conciseness4/5

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

Three short sentences, front-loaded with what the tool returns, followed by behavior (stuck flagging) and usage trigger. No filler, though the parenthetical example is slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is rightly omitted, and annotations carry the safety profile. However, the undocumented 'limit' parameter leaves a real gap in an otherwise simple two-parameter tool.

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

Parameters2/5

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

Only the 'instance' parameter is documented in the schema (50% coverage); 'limit' has no description anywhere. The description mentions neither parameter, so it fails to compensate for the coverage gap that the dimension requires when coverage is below 50-80%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (build queue) and the exact content returned: what is waiting, for how long, and the reason. It is clearly distinguishable from diagnostic siblings like get_build_summary or recent_builds, though it does not name an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Gives a concrete trigger condition — 'useful when builds hang before starting' — which is exactly the scenario an agent would need to recognize. No exclusions or explicit alternatives are stated, so it stops short of a 5.

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

get_stage_logGet Stage LogA
Read-onlyIdempotent

Errors and the last meaningful lines of ONE pipeline stage (default: the failed stage). Much cheaper than the full log. Lines of parallel branches can interleave in the console; exact=True reads the stage step by step from wfapi instead (falls back to the console without the plugin).

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
exactNoPer-step log from the Stage View API (wfapi): exact for parallel branches; more requests
stageNoStage name; empty = the failed stage
instanceNoJenkins instance name from list_instances. Empty = default instance.
max_linesNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already cover the read-only/idempotent/open-world profile, so the description is free to add real behavioral context: cost tradeoff vs. the full log, line interleaving in parallel branches, and that exact=True issues more requests and silently falls back to console scraping if the wfapi plugin is absent. That fallback caveat is exactly the kind of thing an agent needs and the schema cannot express.

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

Conciseness5/5

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

Three dense sentences with the primary scope front-loaded, followed by the cost rationale and then the precision/escalation option. No restatement of the tool name or title, no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be described, and annotations carry the safety profile. The description supplies the cost model and the exact-mode fallback, which covers the main decision risk; only minor gaps remain around truncation behavior via max_lines.

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

Parameters4/5

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

Schema coverage is 83%, so the schema already documents job/build/stage/instance forms. The description still adds meaning for the two parameters where behavior matters most: stage defaults to the failed stage, and exact switches data source and degrades gracefully without the plugin. Only max_lines and the cost implication of exact ('more requests') are left under-explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (ONE pipeline stage log) and the returned content (errors plus last meaningful lines), with the default scope (the failed stage) called out. It contrasts with 'the full log' but never names the sibling tool (get_log_lines / get_log_errors / search_log) that an agent must choose between.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

'Much cheaper than the full log' implies the selection rule (prefer this over the complete log), and 'exact=True ... falls back to the console without the plugin' gives a condition for the alternative mode. But the routing is implicit, not explicit: no sibling names, no statement of when this tool is the wrong choice.

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

get_test_failuresGet Test FailuresA
Read-onlyIdempotent

Failed test cases from the JUnit test report (not the log): class, test, error message, shortened stack, and 'age' = number of consecutive builds this test has been failing.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
instanceNoJenkins instance name from list_instances. Empty = default instance.
max_casesNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent and openWorld, so the bar is lower. The description contributes real value by naming the data source (JUnit report, not log) and defining 'age' as consecutive failing builds, but it does not disclose that results are capped by max_cases (default 20) or what happens when the cap is hit.

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

Conciseness5/5

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

A single sentence, front-loaded with the data source, then the returned fields, then the non-obvious 'age' definition. No filler and no repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be spelled out, and the description still usefully flags the source distinction and 'age' semantics. The remaining gap is the undocumented max_cases cap, which an agent could overlook when a job has many failures.

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

Parameters3/5

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

Schema coverage is 75% and job/build/instance are well documented in the schema itself, so the baseline is 3. The description adds no parameter guidance of its own and leaves max_cases — the one undocumented parameter, whose default silently truncates output — entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Failed test cases from the JUnit test report') and immediately enumerates the returned fields (class, test, error message, shortened stack, age). The parenthetical '(not the log)' explicitly separates it from the log-oriented siblings like get_log_errors and search_log.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

The '(not the log)' clause gives clear selection context: use this for structured JUnit failures rather than for log scraping. It stops short of naming the concrete alternatives (failures_overview, recurring_errors) or stating when-not to use it, so it falls short of a 5.

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

list_artifactsList ArtifactsA
Read-onlyIdempotent

Archived artifacts of a build (relative paths, optionally with sizes) and the download base URL. Read text artifacts with read_artifact; binaries (jar, zip, pdf, xlsx...) are never sent to the model - use the download URL.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
limitNo
sizesNoAlso show file sizes (one HEAD request per file, first 50)
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: binary payloads are never sent to the model and the tool surfaces a download base URL instead. It does not mention output volume or pagination behavior, which keeps it short of a 5.

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

Conciseness5/5

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

Two tight sentences with zero filler; the return content is front-loaded and the follow-up action (read vs. download) comes second. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be explained, and the description covers the one non-obvious constraint (binaries excluded). The remaining gap is the unexplained `limit` cap on listing, which the agent would have to infer from the schema default alone.

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

Parameters3/5

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

Schema coverage is 80% and the schema documents job, build, sizes, and instance thoroughly. The description only reinforces the optional sizes behavior already described in the schema, and it says nothing about the undocumented `limit` parameter. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States exactly what is returned: archived artifact relative paths, optional sizes, and the download base URL for a given build. It also draws the line against read_artifact and the binary-download path, so an agent can distinguish it from siblings like compare_artifacts, list_workspace, and read_artifact without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Explicitly routes the agent: text artifacts go to read_artifact, binaries (jar, zip, pdf, xlsx) must go through the download URL. This names the alternative and the condition that selects it, which is exactly the when/when-not guidance needed.

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

list_instancesList InstancesA
Read-onlyIdempotent

List configured Jenkins instances (name, url, description, default, where the token comes from). check_connection=True also pings each instance and reports the Jenkins version or the error, the token's user and groups, whether it has admin rights, and quiet-down (shutdown) mode. reload_config=True re-reads config/jenkins_instances.yaml and config/.env without restarting the server. Also reports configuration problems and the state of the knowledge base.

NameRequiredDescriptionDefault
reload_configNo
check_connectionNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses important behavior: check_connection performs network pings and reports Jenkins version, authenticated user, groups, admin rights, and quiet-down mode; reload_config re-reads YAML and .env configuration without server restart. It also states that configuration problems and knowledge-base state are reported, which is meaningful behavioral context not supplied by the annotations.

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

Conciseness5/5

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

The description is front-loaded with the core listing behavior, then explains each flag in compact conditional sentences. Despite being moderately detailed, every sentence adds operational meaning rather than restating schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple two-parameter schema, annotations, and presence of an output schema, the description provides enough context for an agent to call the tool correctly. It explains both flags, side effects, and reporting behavior without needing to repeat return-value structure.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must explain the two boolean parameters, and it does: check_connection controls pinging and detailed instance status, while reload_config controls re-reading config files without restart. The implied false behavior is clear from the conditional phrasing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'List configured Jenkins instances,' and enumerates the returned fields (name, url, description, default, token source). This clearly distinguishes it from sibling tools, which focus on jobs, builds, logs, nodes, and knowledge-base content rather than Jenkins instance configuration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

The description gives clear conditions for the two optional flags: check_connection=True pings each instance, and reload_config=True re-reads configuration files without restarting the server. It does not name alternative sibling tools, but no sibling appears to overlap with listing Jenkins instances, so the usage context is sufficiently clear.

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

list_jobsList JobsA
Read-onlyIdempotent

List jobs recursively (folders and multibranch projects are expanded). folder: start below this folder, e.g. 'cd' or 'release'. Empty = whole instance. status: comma list filter on the last build: SUCCESS, FAILURE, UNSTABLE, ABORTED, NOT_BUILT, BUILDING, DISABLED. name_contains: case-insensitive substring filter on the full job name. Each row: 'full/job/name | STATUS #lastBuild | age'. Uses few API calls (no per-job requests).

NameRequiredDescriptionDefault
limitNo
folderNo
statusNo
instanceNoJenkins instance name from list_instances. Empty = default instance.
name_containsNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower; the description still adds real value beyond them by disclosing the cost profile ('Uses few API calls (no per-job requests)'), the recursive expansion behavior, the output row shape, and per-filter semantics. Not a 5 because it doesn't state result-order, truncation at 'limit', or what happens on a nonexistent folder.

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

Conciseness4/5

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

Front-loaded with the action, then one short line per filter — every sentence earns its place and the status enumeration is compressed into a single comma list. Slightly under-specified rather than verbose; the 'Each row' line is a useful addition rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter read tool whose annotations and output schema already carry safety and return-shape, this is close to sufficient: cost, recursion, filters and row format are all covered. The remaining honest gaps are the undocumented 'limit' parameter and the absence of any routing hint against the many sibling listing/discovery tools.

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

Parameters4/5

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

Schema coverage is only 20% (only 'instance' is documented in the schema), so the description carries most of the burden — and it does: it enumerates all seven allowed status values and explains folder prefixing and case-insensitive name matching. The gap is 'limit', which appears in the schema with a default of 100 and is never mentioned, so an agent has no idea whether it caps jobs returned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb + resource ('List jobs') and immediately qualifies scope with '(folders and multibranch projects are expanded)', which is precisely what distinguishes it from get_job or recent_builds. An agent knows it gets a flattened inventory of job paths, not builds or configs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Gives clear operating context: folder scoping ('start below this folder... Empty = whole instance'), status filtering, and substring matching. However it never names an alternative or exclusion — nothing tells the agent when to prefer find_jobs_by_scm or get_job over this, so routing among near-siblings is left to inference.

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

list_known_issuesList Known IssuesB
Read-onlyIdempotent

List knowledge base entries: 'id | status | category | scope | title', plus how many builds each entry matched since the server started. query = case-insensitive text filter on title and content.

NameRequiredDescriptionDefault
queryNo
categoryNo
instanceNoJenkins instance name from list_instances. Empty = default instance.
include_draftsNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds genuinely useful non-obvious behavior: the match counter is scoped 'since the server started', meaning it resets on restart and is not a persistent statistic. It says nothing about ordering, limits, or how pagination behaves for a potentially long listing.

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

Conciseness5/5

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

Two short sentences: the first front-loads what is returned, the second defines the filter. Nothing is redundant and no sentence could be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the column listing is a bonus rather than a necessity. But for a 4-parameter listing tool the description leaves two filters (category, include_drafts) unexplained and gives no routing guidance against find_known_issues, which an agent needs to choose correctly.

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

Parameters3/5

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

Schema coverage is low at 25% — only 'instance' carries a schema description — and the text compensates for exactly one parameter, explaining that query filters case-insensitively on title and content. 'category' and 'include_drafts' remain undocumented in both schema and description, so compensation is only partial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

It states a specific verb ('List') and resource ('knowledge base entries') and even enumerates the returned columns, so the operation is unambiguous. However, it never distinguishes itself from the closely related siblings find_known_issues and get_known_issue, leaving the agent to guess which one is the filtered search versus the plain listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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

There is no statement of when to use this tool versus find_known_issues or get_known_issue, and no mention of preconditions such as needing list_instances first (only implied by the instance param schema). The query-filter sentence describes mechanics, not selection criteria between alternatives.

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

list_workspaceList WorkspaceA
Read-onlyIdempotent

Files in a job's workspace (folders end with '/'), for files that were not archived (e.g. app-queue.log). Pipeline: the workspace of a node block of the build; with several blocks it lists them first. Shows the CURRENT state on the agent. Needs the Job/Workspace permission and a reachable agent.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
pathNoFolder inside the workspace; empty = root
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
node_idNoPipeline only: workspace of which node block (node_id from list_workspace); empty = the only one
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

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

The annotations already establish read-only, idempotent, open-world behavior. The description adds meaningful context beyond them: the listing reflects the CURRENT state on the agent, requires Job/Workspace permission, needs a reachable agent, and explains pipeline node-block behavior when several blocks exist.

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

Conciseness4/5

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

The description is compact and front-loads the core scope before covering pipeline and permission details. It is telegraphic in places, but nearly every sentence carries useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema, full parameter descriptions, and annotations, the description supplies the remaining decision-critical context: current-state semantics, permission and reachability requirements, archived-file exclusion, folder notation, and pipeline node handling. No major call requirement is missing.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema already explains job, path, build, node_id, and instance well. The description still adds non-obvious meaning for node_id handling in pipelines, particularly that multiple node blocks are listed first, which goes beyond the schema wording.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource: files in a job's workspace, excluding archived files, with pipeline node-block nuance. It distinguishes the scope from archived artifacts, though it does not explicitly name sibling tools such as list_artifacts or read_workspace_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

It gives useful context for pipeline workspaces and notes permission/reachability requirements, but it does not explicitly state when to use this tool versus list_artifacts, read_workspace_file, or other workspace/log tools. Usage is therefore implied rather than fully routed.

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

node_healthNode HealthA
Read-onlyIdempotent

Controller and agent status: online/offline (with reason), labels, executors, idle, free disk and temp space, free memory/swap, response time, clock drift, plus warnings. Static agents only; ephemeral Kubernetes agents appear only while they exist. Details of one node: get_node.

NameRequiredDescriptionDefault
instanceNoJenkins instance name from list_instances. Empty = default instance.
only_problemsNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower, but the description still adds meaningful behavior: the ephemeral-Kubernetes visibility caveat explains why a node may be missing from results, which no annotation conveys. It doesn't discuss cost, pagination, or how failures surface as 'warnings', but with an output schema present the field inventory need not be elaborated further.

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

Conciseness5/5

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

Three dense sentences: payload inventory first, scope caveat second, sibling routing last. Every clause carries information, and the most decision-relevant content (what it returns, what it excludes) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read-only listing tool with an output schema, the definition covers purpose, scope, and the detail-level alternative adequately. The one real hole is the undocumented 'only_problems' filter, which an agent would have to infer from the name alone.

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

Parameters2/5

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

Schema coverage is only 50%: 'instance' is documented in the schema, but 'only_problems' has no description anywhere. The prose says nothing about either parameter — not what a filter looks like, not that 'only_problems' narrows the listing — so it does not compensate for the coverage gap on a flag that materially changes the output.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the specific resource (controller and agent status) and enumerates exactly which signals are returned: online/offline with reason, labels, executors, idle state, disk/temp/memory/swap, response time, clock drift, warnings. It also explicitly routes detail-level lookups to the sibling get_node, so an agent can distinguish it from that tool without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

'Static agents only; ephemeral Kubernetes agents appear only while they exist' states a real scope constraint and its consequence. 'Details of one node: get_node' names the alternative tool and the condition that selects it, leaving nothing to inference.

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

propose_kb_updatePropose Kb UpdateA

Propose an update of an EXISTING knowledge base entry instead of writing a duplicate: writes a NEW draft next to it in knowledge/drafts/ with the build URL added to builds, the extra regexes merged in and an 'Update proposal' section. Never touches the entry itself or Jenkins, never overwrites a file. Reports whether the entry matches the given build.

NameRequiredDescriptionDefault
idYesReviewed entry to update, e.g. KB-0001
jobNoJob full name or Jenkins URL. Empty = not tied to a build.
noteNoWhat is new: another occurrence, a better fix, a wrong regex...
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
instanceNoJenkins instance name from list_instances. Empty = default instance.
add_matchNoPython regexes (case-insensitive). Use specific phrases copied from the log, not generic words like 'ERROR'.
add_consequencesNoPython regexes (case-insensitive). Use specific phrases copied from the log, not generic words like 'ERROR'.
add_red_herringsNoPython regexes (case-insensitive). Use specific phrases copied from the log, not generic words like 'ERROR'.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already declare a non-destructive, non-read-only, non-idempotent write, and the description adds substantial detail beyond them: it writes a separate draft rather than mutating the entry, never touches the entry itself or Jenkins, never overwrites a file, and reports whether the entry matches the given build. This is exactly the extra context the annotations cannot convey.

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

Conciseness4/5

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

The distinguishing constraint is front-loaded in the first clause, and each subsequent sentence adds distinct information about what is created and what is left untouched. The one long sentence packing three draft modifications is dense but not wasteful; only minor tightening is possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present the description need not explain return values, yet it still notes that the call reports build-match status. Safety and side effects are fully covered for an 8-parameter write tool. What is missing is only marginal: no mention of what happens on an unknown or un-reviewed id.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter (id, job, note, build, instance, add_match, add_consequences, add_red_herrings) is already documented in the schema. The description reinforces that the regex arguments are merged into the existing entry and that build data is appended, but adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Propose an update of an EXISTING knowledge base entry') and immediately contrasts it with the duplicate-creating alternative. The concrete effect — a new draft under knowledge/drafts/ with the build URL appended, regexes merged, and an 'Update proposal' section — makes the outcome unambiguous and distinguishes it from siblings like draft_kb_entry.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

The opening clause gives a clear when-to-use rule: prefer this over writing a duplicate when an entry already exists. It also implies the precondition that the target must be an existing reviewed entry (id, e.g. KB-0001). It stops short of naming a sibling tool or stating explicit when-not conditions, so it is clear context rather than full routing guidance.

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

read_artifactRead ArtifactA
Read-onlyIdempotent

Read a text artifact (reports, logs, yaml, json...). With pattern it greps (regex, case-insensitive, 1 line context, max 50 matches); otherwise returns count lines from start (0 = tail). Secrets are masked. UTF-8, UTF-16 (with BOM) and cp1252 files are decoded; binary files are refused.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
pathYesrelativePath from list_artifacts
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
countNo
startNo
patternNo
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only declare it is a safe idempotent read; the description goes well beyond that with secrets masking, binary refusal, supported encodings (UTF-8/UTF-16 BOM/cp1252), 1-line grep context and a 50-match cap. These are behavioral traits an agent cannot infer from the schema or annotations.

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

Conciseness5/5

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

Three dense, front-loaded sentences covering modes, limits, encoding and security behavior with no filler. Terse fragments ('0 = tail', '1 line context') trade grammar for information density without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return shape needn't be described, and the description nonetheless covers the tricky parts: mode selection, match cap, masking, and decode/refusal behavior. Minor gap: it doesn't say how to detect a truncated line window or that grep results are capped rather than complete.

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

Parameters4/5

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

Schema coverage is 57%, with job, build and instance documented in the schema but count/start/pattern left bare. The description compensates by defining pattern as case-insensitive regex with context and match cap, and by explaining count/start semantics including the non-obvious '0 = tail'. Job/build/instance meaning is not repeated, which is correct since the schema already carries it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Read a text artifact') and enumerates the file kinds it covers (reports, logs, yaml, json). An agent can tell it is a file-content reader, though it never distinguishes itself from close siblings like read_workspace_file, read_managed_file, or get_log_lines.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

The description implicitly splits usage into two modes – grep via `pattern` versus line-window via `count`/`start` – which is helpful operational guidance. But it gives no explicit when-to-use versus the sibling readers, and no exclusions (e.g., 'for workspace files use read_workspace_file').

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

read_managed_fileRead Managed FileA
Read-onlyIdempotent

Content of a Config File Provider managed file (settings.xml, .npmrc, properties...) with secrets masked. Global files by default; pass folder= for files defined in a folder.

NameRequiredDescriptionDefault
idYesManaged file id (fileId / settingsConfigId) as shown by get_job_config
folderNoFolder that defines the file; empty = global (Manage Jenkins > Managed files)
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely new context: secrets are masked in the returned content, and the global-vs-folder resolution default. That is useful beyond what the structured fields convey.

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

Conciseness4/5

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

Two tight sentences, front-loaded with what is returned and the masking guarantee before the folder scoping note. The parenthetical file-type examples earn their space by making the resource concrete; there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-shape explanation is unnecessary, and the three params are fully documented in the schema. With read-only annotations plus the explicit secrets-masking and default-scope notes, an agent has enough to call this correctly; only cross-tool routing guidance is absent.

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

Parameters3/5

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

Schema description coverage is 100%, so all three parameters are already documented, including the empty-default semantics for folder and instance. The description's 'Global files by default; pass folder=...' restates the folder default and adds the id provenance hint, but nothing more — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb+resource ('Content of a Config File Provider managed file') and gives concrete examples of the file types (settings.xml, .npmrc, properties), plus a key behavior (secrets masked). It does not explicitly distinguish itself from read_workspace_file or read_artifact, which is the only gap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

The description implies usage via 'Global files by default; pass folder= for files defined in a folder' and points to get_job_config as the source of the id. However, it never states when to choose this over sibling read tools such as read_workspace_file or read_artifact, leaving the agent to infer.

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

read_workspace_fileRead Workspace FileA
Read-onlyIdempotent

Read a text file from a job's workspace (e.g. a log the build did not archive). With pattern it greps (regex, case-insensitive); otherwise count lines from start (0 = tail). UTF-8, UTF-16 and cp1252 are decoded, binary files refused, secrets masked. Shows the CURRENT file on the agent.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
pathYesFile path inside the workspace
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
countNo
startNo
node_idNoPipeline only: workspace of which node block (node_id from list_workspace); empty = the only one
patternNo
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior4/5

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

Beyond the readOnly/idempotent annotations, the description discloses real behavior: supported encodings (UTF-8, UTF-16, cp1252), that binary files are refused, that secrets are masked, and that it shows the CURRENT file on the agent rather than a historical snapshot. Missing size/truncation limits and error behavior for a missing file keep it from a 5.

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

Conciseness4/5

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

Four tight sentences, front-loaded with the purpose and mode selection before the encoding/masking caveats. Nothing is padded, though the phrasing is compressed enough that "0 = tail" and "the agent" require a second read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 parameters, a 63% schema coverage, and an output schema already defining the return shape, the description covers the remaining risk surface: file encodings, binary rejection, secret masking, and the live-vs-archived workspace caveat. An agent has what it needs to call this correctly.

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

Parameters4/5

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

Schema coverage is only 63%, and the description compensates for the undocumented parameters: `pattern` is clarified as regex and case-insensitive, and `start`/`count` are defined in relation to each other with "0 = tail". Only `node_id` and `instance` semantics are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource ("Read a text file from a job's workspace") and scopes it with the parenthetical "a log the build did not archive", which implicitly separates it from the artifact-reading siblings. It does not name read_artifact or read_managed_file explicitly, so the differentiation is inferential rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

The two operating modes are spelled out: "With `pattern` it greps (regex, case-insensitive); otherwise `count` lines from `start` (0 = tail)", which tells an agent how to choose between search and pagination. It never says when to prefer a sibling (e.g. read_artifact for archived files) or what to do when the file is absent.

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

recent_buildsRecent BuildsA
Read-onlyIdempotent

Every build (not only the last one per job) started in the last hours, across one or all instances in parallel, newest first: 'job #n RESULT duration age | culprits | long-running note'. Counts per result. Uses ~1 request per instance (up to 10 newest builds per job are checked). Good for 'what ran/failed today', a morning check or a stand-up.

NameRequiredDescriptionDefault
hoursNo
folderNo
statusNoComma list: SUCCESS, FAILURE, UNSTABLE, ABORTED, NOT_BUILT, BUILDING. Empty = all
instanceNoInstance name or 'all'all
limit_per_instanceNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior5/5

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

Beyond the annotations, it discloses important behavior: parallel instance querying, request cost (~1 request per instance), sampling limits (up to 10 newest builds per job checked), output shape, and result counts. These are exactly the operational details an agent needs before invoking the tool.

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

Conciseness5/5

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

The description is dense but front-loaded and every sentence adds useful information about scope, output, cost, or intended use. There is little wasted text despite the amount of detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description provides strong context on scope, output format, sampling, and use cases. It is slightly incomplete on the `folder` and `limit_per_instance` parameters, but otherwise gives an agent enough to invoke the tool correctly.

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

Parameters2/5

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

Schema description coverage is only 40%, so the description should compensate more than it does. It explains `hours` and `instance`, but does not explain `folder` or `limit_per_instance`, and only indirectly relates to `status` through 'Counts per result'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the resource and scope: all builds started within the last `hours`, across one or all instances, newest first. It distinguishes itself from a last-build-per-job view, but does not explicitly name a sibling tool, so it falls short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

It gives concrete usage contexts: 'what ran/failed today', a morning check, or a stand-up. It does not state when not to use it or name an alternative such as `get_build_summary`, but the intended context is clear.

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

recurring_errorsRecurring ErrorsA
Read-onlyIdempotent

Error groups across the newest finished builds of one job (max 20): in how many failed and green builds each occurs, first/last build, and a verdict - 'new since #N' (regression) or 'also in green builds' (red_herring candidate for the knowledge base). Knowledge base notes are attached. Cost: one log per build (cached afterwards).

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
last_nNo
instanceNoJenkins instance name from list_instances. Empty = default instance.

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover read-only/idempotent safety, and the description adds genuinely useful operational context: a cap of 20 error groups, the verdict classification logic, KB note attachment, and an explicit cost model ('one log per build, cached afterwards'). It stops short of describing caching lifetime or how 'newest finished builds' are selected.

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

Conciseness4/5

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

Purpose is front-loaded and every clause carries information (verdict semantics, KB notes, cost). The telegraphic multi-clause sentence and dangling '(max 20)' placement add slight parsing friction, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only analytical tool with an output schema, the description supplies what the schema cannot: verdict meaning, the KB linkage, and the log-read cost. Only the last_n semantics and the exact build window remain underspecified.

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

Parameters3/5

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

Schema coverage is 67%: job and instance are documented, but last_n has no description at all. The description's 'newest finished builds ... (max 20)' is the only hint about how many builds are scanned, and it does not clearly reconcile with last_n's default of 8, leaving the control ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific analysis verb over a specific resource: recurring error groups aggregated across the newest finished builds of one job, with counts in failed vs green builds, first/last build, and a verdict. The aggregation-over-builds framing naturally separates it from per-build siblings like get_log_errors or get_build_summary, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Use is implied by the verdict labels ('regression', 'red_herring candidate for the knowledge base') and the note that KB notes are attached, which hints at a triage workflow. However, there is no explicit statement of when to call this versus failures_overview, get_log_errors, or find_known_issues, and no stated prerequisites.

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

search_logSearch LogA
Read-onlyIdempotent

grep -C for a build log: matching lines with context lines around them and line numbers. Optionally restricted to one stage. Reports the total number of matches even if only max_matches are shown.

NameRequiredDescriptionDefault
jobYesJob full name like 'cd/master/my-app' (folders separated by '/'), or a Jenkins job/build URL (instance is then detected from the URL).
buildNoBuild number or permalink: lastBuild, lastFailedBuild, lastSuccessfulBuild, lastCompletedBuild, lastUnsuccessfulBuild. Empty = build from the URL, else lastBuild.
stageNo
contextNo
patternYesPython regex (invalid regex is treated as literal text)
instanceNoJenkins instance name from list_instances. Empty = default instance.
ignore_caseNo
max_matchesNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description still adds real behavioral context: results are truncated at max_matches but the total match count is always reported, so an agent knows it can detect hidden matches. It stops short of describing the output shape or what happens on zero matches, but the truncation disclosure is the substantive part.

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

Conciseness5/5

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

Three tight sentences, front-loaded with the grep analogy that carries most of the explanatory weight, then two qualifications. No filler and nothing repeated from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is unnecessary, and the schema documents the job/build/instance parameters. For an 8-parameter read-only search tool, the description supplies the behaviors an agent cannot get from structured fields: context semantics, stage scoping, and truncation with total-count reporting.

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

Parameters3/5

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

At 50% schema coverage the description must compensate, and it does for three of eight parameters: `context` (lines around the match), `stage` (optional restriction to one stage), and `max_matches` (a cap, with total matches still reported). The remaining parameters (job, build, instance, ignore_case) are either covered by the schema or left unaddressed, so the description adds partial rather than full meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The 'grep -C for a build log' framing states a precise verb+resource and immediately conveys the differentiating behavior (matching lines plus surrounding context and line numbers). It implicitly separates itself from full-log siblings like get_log_lines and get_stage_log, but never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

'Optionally restricted to one stage' and the grep analogy imply when the tool fits, but there is no explicit guidance on when to prefer it over get_log_lines, get_log_errors, or get_stage_log, nor any stated prerequisites. The usage is inferable rather than directed.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 34 tool updatesv1.0.0
    • First observedcompare_artifacts
    • First observedcompare_builds
    • First observeddiff_job_config
    • First observeddraft_kb_entry
    • First observedfailures_overview
    • First observedfind_jobs_by_scm
    • First observedfind_known_issues
    • First observedget_build_summary
    • First observedget_env_log
    • First observedget_job
    • First observedget_job_config
    • First observedget_job_config_history
    • First observedget_known_issue
    • First observedget_log_errors
    • First observedget_log_lines
    • First observedget_node
    • First observedget_pending_inputs
    • First observedget_pipeline_info
    • First observedget_queue
    • First observedget_stage_log
    • First observedget_test_failures
    • First observedlist_artifacts
    • First observedlist_instances
    • First observedlist_jobs
    • First observedlist_known_issues
    • First observedlist_workspace
    • First observednode_health
    • First observedpropose_kb_update
    • First observedread_artifact
    • First observedread_managed_file
    • First observedread_workspace_file
    • First observedrecent_builds
    • First observedrecurring_errors
    • First observedsearch_log

TDQS

A3.7/5.0

Scored across 34 tools

Disambiguation4/5

Purpose clusters (log inspection, artifacts, jobs, nodes, knowledge base) are well delineated and descriptions give explicit guidance like 'START HERE' and 'use this instead'. The main risk is the dense family of log tools (get_build_summary, get_log_errors, get_stage_log, search_log, get_log_lines, recurring_errors) where boundaries are clear only after reading the full descriptions.

Naming Consistency4/5

Mostly verb_noun snake_case (get_build_summary, list_jobs, compare_builds, read_artifact, find_known_issues). A handful drop the verb (node_health, failures_overview, recent_builds, recurring_errors), which is a minor but noticeable deviation from the otherwise predictable pattern.

Tool Count3/5

34 tools is heavy, well above the comfortable 3-15 range. The Jenkins debugging domain is genuinely broad (logs, artifacts, jobs, config, nodes, queue, KB, workspace) and most tools earn their place, but the surface is large enough to burden tool selection.

Completeness5/5

Coverage is unusually thorough across builds, logs, artifacts, test failures, job/node/queue state, config history and diffing, knowledge base lifecycle, and workspace reads. The only apparent gap is write/action operations (triggering, aborting, approving inputs), which seem intentionally excluded as a safety choice and are explained as such.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    C
    maintenance
    Provides AI assistants with persistent memory of your project architecture, development history, and technical decisions, allowing them to give context-aware coding help without needing repeated explanations.
    16
    61 npm
    2
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Enables LLMs to automatically diagnose coding errors through codebase search, test execution, and live debugger integration (DAP/V8 CDP). Provides a secure, policy-gated environment for investigating failures while preventing destructive operations.
    9
    ISC
  • A
    license
    A
    quality
    C
    maintenance
    Enables AI assistants to access full Datadog observability, including log search, APM trace filtering, smart sampling, and cross-correlation between logs, traces, and metrics.
    23
    2,047 npm
    6
    Apache 2.0
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI coding agents to access evidence-backed repository memory, code graph, project DNA, and deterministic change validation so they understand design decisions, past bugs, and invariants while working.
    833 npm
    15
    Functional Source , Version 1.1, ALv2 Future