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

With no annotations, the description carries the full burden and does so: it labels the operation destructive, states the concrete consequence ('the request to build is discarded'), and enumerates the three required permissions (MCP_ALLOW_BUILD_WRITE, MCP_ALLOW_DESTRUCTIVE, MCP_ALLOW_BUILD_STOP). This is exactly the behavioral context an agent needs before calling a mutation tool.

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

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

Front-loads purpose, then destruction, then parameter source, then the alternative tool, then auth requirements. Every sentence adds distinct information with no repetition of the schema.

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

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

For a single-argument cancel tool with no output schema, the definition covers purpose, consequence, argument provenance, sibling routing, and permission prerequisites. 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.

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

Schema coverage is 0% and there is a single parameter, so the description must compensate. It does well by naming the source of item_id (get_queue) and explicitly disambiguating it from a build number, but it does not describe the integer format or error behavior for stale/invalid ids beyond what the schema implies.

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

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

States a specific verb (Remove/cancel) and resource (queued item) with precise scope ('before it starts'), and explicitly contrasts with the sibling stop_build for running builds. An agent can distinguish it from get_queue_item and stop_build 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.

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

Names the alternative (stop_build) and the exact condition that selects it (build already running), defining when NOT to use this tool. It also tells the agent where the required argument comes from (get_queue), 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.

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

With no annotations, the description carries the burden well: it discloses what the copy inherits (settings, enabled/disabled state), what is deliberately not copied (build history, workspaces), an environment-level constraint (MCP_ALLOWED_JOBS), and the Jenkins permissions required (Job/ExtendedRead on source, Job/Create on target parent, Job/Configure when secrets are redacted). It stops short of stating what happens if the target already exists or whether it errors/overwrites.

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

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

Front-loaded with the action, then the copy semantics, then the constraints. Four dense sentences with almost no filler; the permission clause reads as a list but every item is actionable information rather than padding.

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

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

For a two-param mutation tool with no annotations and no output schema, the description covers inheritance semantics, scope gating, and authorization. The remaining gap is failure behavior (existing target, permission-denied outcome), which an agent would need to call this confidently, but the essentials are present.

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

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

Schema description coverage is 0%, so the two parameters (source_job, target_job) rely entirely on the description. It adds a meaningful constraint that both must be in MCP_ALLOWED_JOBS, but gives no format guidance (full path vs name), no path-shape example, and no statement on whether target_job may pre-exist.

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

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

States a specific verb and resource ('Copy an existing job's configuration to a new name') and explicitly scopes what is and isn't inherited (settings/state yes, history/workspaces no). That scope statement implicitly separates it from siblings like create_job_from_xml and update_job_config, though no sibling is named.

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

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

Provides real operating context (both jobs must be inside MCP_ALLOWED_JOBS, source/target permission requirements) but never says when to prefer this over create_job_from_xml, create_pipeline_job, or update_job_config, nor any when-not condition. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses the duplicate-name failure mode, a security rule about not embedding plaintext credentials (use Jenkins-managed credential IDs), and a request-size ceiling. It stops short of covering permissions/auth requirements or what happens to the job after creation, but this is unusually rich behavioral context for an unannotated tool.

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

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

Four short, front-loaded sentences with no filler: purpose first, then failure/alternatives, then the security warning, then the size constraint. Every sentence carries distinct operational information.

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

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

For a no-annotation, no-output-schema, two-param creation tool, the description covers usage, failure behavior, security, and size limits. Return-value details are absent, but the tool's response is low-stakes and the main decision inputs are all present.

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

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

Schema description coverage is 0% with two required parameters, so the description must compensate. It clarifies config_xml as 'raw config.xml' and adds the encoded-body size limit, but job_name is left entirely unexplained. Partial compensation only.

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

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

States a specific verb and resource ('Create a job from a raw config.xml') and explicitly distinguishes itself from the sibling creation tools create_pipeline_job and create_multibranch_pipeline. An agent can tell exactly what this tool produces and when it is the right choice.

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

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

Gives explicit routing advice: 'Prefer create_pipeline_job or create_multibranch_pipeline unless you need full control of the XML,' naming the alternatives and the condition that selects them. It also states a precondition (fails if the name already exists) and a constraint on use (body must fit MCP_MAX_REQUEST_BYTES).

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses plugin dependencies, a hard payload limit ('generated XML must fit MCP_MAX_REQUEST_BYTES'), credential-handling rules ('never pass a token, password or private key'), and URL/path validity constraints. These are exactly the failure modes an agent needs warned about before calling a write tool.

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

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

Purpose is front-loaded and every subsequent sentence encodes a distinct constraint, so there is no filler. The constraint clauses run together in one dense block without sub-structuring, which slightly harms scannability but wastes no words.

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

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

For a five-parameter mutation tool with no annotations and no output schema, the description covers the operationally risky details (credentials, URL format, size limit) thoroughly. It does not explain what happens on name collision or what the call returns, but return format is arguably outside its remit.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning for three of five parameters: repository_url restrictions (no embedded credentials, query string, or fragment), credentials_id semantics (must name a stored Jenkins credential, not a raw secret), and script_path canonicality. job_name and description receive no guidance, leaving a small gap.

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

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

The description opens with a precise verb+resource+scope: 'Create a multibranch Pipeline that discovers branches from a Git repository.' The 'multibranch' qualifier implicitly separates it from the sibling create_pipeline_job, but it never names that sibling or explicitly contrasts a single-branch pipeline, so an agent must infer the distinction.

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

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

It gives clear operational context: plugin prerequisites (workflow-multibranch, branch-api, git) and the follow-up step 'Run scan_multibranch_pipeline afterwards to populate branches immediately', which ties this tool to a named sibling. It stops short of stating when NOT to use this tool or when create_pipeline_job would be the better choice.

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

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

With no annotations, this description carries the full burden and does notable work: Groovy sandbox execution, required plugins, credential-ID-only guidance against plaintext secrets, and a MCP_MAX_REQUEST_BYTES size constraint. It stops short of stating idempotency (behavior when the job already exists) or the response shape.

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

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

Four short sentences, purpose front-loaded, each sentence contributing a distinct operational fact. No redundancy or padding.

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

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

For a mutation tool with zero annotations and no output schema, the description covers environment, security, and size constraints well. It leaves gaps on return values and what happens on name collision, but is otherwise sufficiently complete.

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

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

Schema coverage is 0%, so the description must compensate. It adds genuine content constraints for the jenkinsfile parameter (sandbox, credential references, size limit), but job_name and description remain undocumented beyond self-explanatory titles, so coverage is partial.

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

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

States a specific verb (Create), resource (Pipeline job), and source format (inline Jenkinsfile). The 'inline Jenkinsfile' scoping cleanly separates it from create_job_from_xml and create_multibranch_pipeline without needing to name them.

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

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

Prerequisites are spelled out (workflow-job and workflow-cps via workflow-aggregator), which implies the environment needed to use it. However, it never says when to prefer this over create_job_from_xml or create_multibranch_pipeline, so alternative selection 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.

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

With no annotations, the description carries the full burden and does so: it declares the operation destructive and irreversible, explains why recovery needs an external backup, and enumerates the exact environment gates that must be enabled. This is exactly the behavioral context an agent needs before firing an unrecoverable write.

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

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

Three short sentences, front-loaded with the destructive outcome, then recovery implications, then prerequisites. Every sentence carries distinct, actionable information with no filler.

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

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

For a single-parameter destructive tool with no annotations and no output schema, the definition covers what is removed, irreversibility, and the required gating flags. Only minor gaps remain: no statement of error behavior for a non-existent job and no explicit non-destructive alternative.

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

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

Schema description coverage is 0% and the single parameter 'job_name' has no schema description, so the description is the only place semantics could be supplied. It never states the expected identifier form (display name vs. full path vs. URL segment) or what happens on a name mismatch, adding essentially no meaning beyond the schema's field name.

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

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

States a specific verb and resource with scope ('Delete a job and all of its build history'), which cleanly separates it from siblings like disable_job or list_jobs. The addition of 'all of its build history' disambiguates the blast radius beyond a bare delete.

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

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

Gives clear preconditions ('Disabled by default; requires MCP_ALLOW_JOB_WRITE, MCP_ALLOW_DESTRUCTIVE and MCP_ALLOW_JOB_DELETE') and a workflow directive ('Confirm with get_job first'). It does not name a non-destructive alternative such as disable_job for the case where history should be preserved, so it stops short of full when-not guidance.

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

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

With no annotations, the description must carry the behavioral load, and it does: queued builds are unaffected, the job and its history survive, and the action is reversible. It omits what happens to currently running builds and any permission requirements, 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.

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

Three short sentences, zero filler, and the core effect is front-loaded before the caveats and the alternative-tool pointer. Every sentence earns its place.

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

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

For a reversible state-change tool with no annotations and no output schema, the description covers the essential behavior an agent needs: effect, side-effect boundary, reversibility, and an alternative. Only permission/authorization context and the running-build question are missing.

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

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

Schema description coverage is 0% and the description never mentions job_name or its expected format. Given there is exactly one self-evident required parameter, this is a minor gap rather than a damaging one, so a baseline 3 is appropriate.

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

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

States a specific verb (disable) and resource (job) with the effect ('so Jenkins stops building it'), and distinguishes itself from siblings by naming cancel_queue_item and enable_job. An agent can route between disable_job, enable_job, cancel_queue_item, and delete_job 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.

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

Explicitly routes the agent away from this tool when the goal is cancelling queued builds ('use cancel_queue_item for those') and notes reversibility via enable_job. It stops short of a direct when-to-use-vs-delete_job statement, but the alternative coverage is clear.

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

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

With no annotations, the description carries the full burden. It usefully discloses idempotency (safe on an already-enabled job), which is real behavioral value, but omits permissions needed, error behavior for a missing job, and whether the change is reversible.

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

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

Two short sentences with the action stated first and the safety note second. Nothing is padded or redundant.

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

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

For a single-parameter mutation with no annotations and no output schema, the idempotency note covers the most important behavioral trait, but the undocumented parameter and absent auth/error context leave gaps an agent would need.

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

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

One parameter at 0% schema coverage means the description must compensate, and it does not: job_name is never described, so an agent gets no guidance on format (plain name vs folder path) or valid values.

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

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

States a specific verb+resource ('Enable a job') and adds the effect ('so Jenkins will build it'). The sibling set includes disable_job, so the direction of the toggle is unambiguous, though it never names the sibling explicitly.

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

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

The clause 'Safe to call when already enabled' gives useful idempotency guidance, but there is no explicit statement of when to enable versus alternatives, nor any prerequisites or permission requirements.

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

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

With no annotations, the description carries the full burden and does disclose real behavior: output is truncated to MCP_MAX_LOG_BYTES, pagination continues via the returned next_start, and invalid/incomplete pagination metadata is refused rather than guessed. It omits auth requirements and what happens for a nonexistent build or job.

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

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

Four tight sentences, front-loaded with the core action, then truncation, then continuation, then alias/error behavior. Every sentence carries distinct, non-redundant information with no filler.

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

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

With no annotations and no output schema, the description still covers the return shape (truncated log plus next_start) and the continuation loop, plus an error-refusal policy. It stops short of describing failure modes like missing jobs/builds or permission requirements, which an agent might need.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents two of three parameters meaningfully: build_number accepts a number or an alias such as lastBuild, and start is the continuation cursor fed by next_start. Only job_name is left to inference, and it is self-evident from the name.

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

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

States a specific verb and resource: 'Read a build's console output.' This implicitly separates it from the sibling get_build_info (metadata) by naming the console output, but it never explicitly names or contrasts any sibling, so a 4 rather than a 5.

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

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

It supplies one usage context implicitly: 'which is how a running build is followed,' telling the agent this tool is the way to tail a live build. It gives no explicit when-not guidance or named alternative (e.g. get_build_info for status), so guidance is implied rather than spelled out.

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

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

With no annotations, the description carries the full burden and does real work here: it discloses that secret-like parameter names and password/token/credential classes are redacted, and that complex plugin values and action/change-set payloads are omitted. That is substantive behavioral disclosure about the shape and safety of the response. It stops short of stating read-only semantics, auth requirements, or behavior for a nonexistent build.

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

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

Three compact sentences, front-loaded with the core purpose, then parameter semantics, then output caveats. Every sentence adds information and none is filler.

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

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

With no output schema and no annotations, the description does the heavy lifting: it summarizes the returned fields and flags redaction and payload omissions. The main gap is the undescribed required job_name parameter and no note on failure behavior when a build does not exist.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain build_number well (integer or aliases lastBuild/lastSuccessfulBuild/lastFailedBuild), but job_name is never described at all, leaving one of two parameters undifferentiated across schema and description.

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

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

The description names a specific verb and resource ('Get one build's result') and enumerates exactly what is returned: result, timing, duration and parameters. That field list distinguishes it from siblings like get_build_console or list_running_builds without needing to open either schema.

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

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

Usage context is implied by the returned fields (build status/timing rather than console text), but the description never states when to prefer this over get_build_console, get_job, or list_running_builds, nor any exclusions or prerequisites. Guidance is present only at the parameter level (alias values), not at the tool-selection level.

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

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

No annotations are provided, so the description carries the full burden. It discloses meaningful behavioral content beyond the schema by enumerating what is and is not returned, and 'current state' implies a read operation, but it does not mention permission requirements or side-effect profile explicitly.

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

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

Front-loaded with the resource and return contents, followed by scoping and exclusions in two tight sentences. Every clause carries routing or scope information; nothing is redundant.

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

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

With no output schema and no annotations, the description fills the main gap by describing the returned fields and exclusions. It is sufficient for correct invocation, though permission and error behavior are left unstated.

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

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

Schema coverage is 0% and there is one parameter (job_name) with no description. The parameter name is largely self-evident, but the description adds no format, identification, or addressing guidance to compensate for the coverage gap.

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

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

States a specific verb (Get) and resource (one job) and enumerates exactly what is returned: description, buildable flag, health, and recent build references. It distinguishes itself from get_job_config and get_build_info directly, so an agent can separate this from its siblings 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.

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

Explicitly routes to alternatives with conditions: get_job_config for the XML definition, get_build_info for a specific build. It also states what is out of scope (plugin actions, upstream/downstream job objects), which is exactly the when-not guidance an agent needs.

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

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

With no annotations, the description carries the full burden and does add real operational context: it requires Job/ExtendedRead and will 403 with Job/Read alone. That failure-mode disclosure is valuable, though it does not state read-only semantics explicitly (implied by 'Fetch') or output behavior.

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

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

Two tight sentences with the action front-loaded and the permission caveat immediately after. No wasted words.

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

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

Output schema exists so return values need no explanation, and the auth caveat covers the main non-obvious risk. Only the job_name semantics and sibling routing remain unaddressed, which is a minor gap for a single-param read tool.

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

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

Schema description coverage is 0% for the single job_name parameter, and the description adds no format or naming guidance for it. It neither compensates for the gap nor misleads, so it sits at the minimum viable level.

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

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

States a specific verb and resource: fetch a job's config.xml definition. This clearly distinguishes it from generic metadata fetches, though it does not explicitly contrast with sibling get_job, which also pertains to a single job.

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

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

No explicit when-to-use or when-not guidance versus alternatives like get_job or update_job_config. Usage is only implied by the fact that it returns the raw config.xml, which the agent must infer.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavioral traits: current-build details are deliberately excluded, and node names are case sensitive and cannot be empty. It does not state the safety/read-only nature explicitly or the response shape, but the input constraints and exclusions are substantive.

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

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

Three short sentences, front-loaded with what is returned before the exclusions and input constraints. Slightly awkward line wrapping but no wasted content.

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

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

With no annotations and no output schema, the description supplies the return fields, the intentionally excluded data, an alternative tool, and the input validation rules. The one gap is that it never characterizes the operation as a safe read, but an agent has enough to call it correctly.

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

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

Schema description coverage is 0% for the single node_name parameter, so the description must compensate, and it does by specifying case sensitivity and that the value must not be empty. This adds meaning well beyond the bare 'string' type in the schema.

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

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

States a specific verb and resource ('Get one node's') and enumerates the exact data returned: capacity, idle state, offline reason. It also distinguishes itself from the sibling list_running_builds, so an agent can tell it apart without opening another schema.

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

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

Explicitly routes the agent to list_running_builds for current-build details and explains why they are excluded here. It does not name the more directly competing sibling list_nodes (for enumerating all nodes) or set_node_offline, so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the full burden and does well: it discloses the item lifecycle (no build number until an executor picks it up), an authorization-based filter (MCP_ALLOWED_JOBS), and explicit negative scope (queue actions and build-parameter values are not returned). It stops short of mentioning ordering, staleness, or whether the call is read-only in cost terms.

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

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

Three sentences, all front-loaded onto the payload-defining facts, with zero filler. Each sentence adds a distinct piece of information: what is listed, what a queue item is, and what is filtered out.

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

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

For a zero-parameter, no-annotations, no-output-schema read tool, the description covers identity, lifecycle, filtering, and excluded fields well. Remaining gaps are minor (ordering of items, how blocked reasons are formatted).

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter surface for the description to compensate for or contradict.

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

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

States a specific verb and resource ('List builds') plus its distinguishing scope ('waiting to start'), which separates it from siblings like list_running_builds and get_queue_item. The clarifying sentence that a queue item is 'not a build yet' and has no build number pins down exactly what set is returned.

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

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

The MCP_ALLOWED_JOBS filtering constraint implies when results will be incomplete, but the description never says when to reach for get_queue versus get_queue_item or list_running_builds. Usage is inferable from the concept, not stated.

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

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

With no annotations the description carries full load, and it delivers real behavioral context: the response explains why an item is blocked, the 'executable' field appears once Jenkins starts the build, and completed queue records are only briefly retained. It stops short of declaring read-only status or permission/auth requirements.

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

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

Front-loaded with the tool's purpose, then lifecycle and caveats. Four sentences with little waste, though it is dense and packs several distinct points together.

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

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

No annotations or output schema, so the description must supply everything. It covers response contents (block reason, executable fields), the calling workflow, an access constraint, and a retention caveat — nearly complete, missing only explicit read-only/permission framing.

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

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

Schema coverage is 0% for the single 'item_id' parameter, so the description must compensate. It explains provenance ('Pass queue_id from trigger_build'), but the mismatch between the schema name 'item_id' and the description's 'queue_id' risks confusing the agent about what value to supply.

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

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

States a specific verb+resource: 'Follow one queued build from trigger to executor assignment.' This clearly distinguishes it from siblings like get_queue (list all), cancel_queue_item (cancel), and trigger_build (create).

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

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

Names trigger_build as the source of the id and get_build_info as the downstream consumer, establishing the workflow context. It also states a hard constraint (owning job must match MCP_ALLOWED_JOBS), but gives no explicit when-not-to-use or contrast with get_queue.

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

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

With no annotations present, the description carries the full burden and does so thoroughly: gate flags, that non-read methods mutate or delete state and are NOT gated by MCP_ALLOW_DESTRUCTIVE, that session/CSRF headers are withheld from responses, that raw 3xx responses are passed through unlike typed tools, and the MCP_MAX_REQUEST_BYTES limit.

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

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

Front-loaded with purpose and the escape-hatch framing, then the gating and safety notes. Dense and mostly economical, though the run of environment-variable clauses makes it slightly heavier than necessary.

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

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

For a high-risk arbitrary-request tool with no annotations and no output schema, the description covers gating, mutation risk, header stripping, redirect behavior, and size limits. An agent has everything needed to invoke it safely and interpret the non-standard response handling.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that path is Jenkins-relative and absolute with the example '/api/json', and that the encoded body must fit MCP_MAX_REQUEST_BYTES. Method semantics (allowed HTTP verbs) are only implied rather than spelled out, so it falls short of full compensation.

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

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

States a specific verb and resource: 'Send an arbitrary authenticated request to a Jenkins path.' It also positions itself against siblings by calling itself 'a powerful escape hatch for endpoints no other tool covers,' so an agent can distinguish it from the typed mutation tools 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.

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

Explicitly defines when to use it ('endpoints no other tool covers') and when it will not work: disabled by default, needs MCP_ALLOW_ADMIN_REQUEST, MCP_ALLOWED_JOBS applies to job URLs, and the Groovy console needs MCP_ALLOW_SCRIPT_CONSOLE. It also warns to confirm method/path/body before non-read calls.

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

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

With no annotations, the description carries the full burden and does disclose real behavioral traits: it filters results through MCP_ALLOWED_JOBS, omits rather than errors on disallowed jobs, and explicitly limits payloads by excluding plugin action/property data. It does not mention pagination, result-size limits, or auth requirements, so it is strong but not complete.

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

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

Four short sentences, front-loaded with the core purpose followed by return fields and behavioral caveats. Every sentence adds information an agent needs; no filler or restatement of the tool name.

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

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

With no output schema and no annotations, the description correctly fills the gap by enumerating returned fields (name, full path, URL, build colour) and the allowlist filtering behavior. It leaves pagination and error/auth conditions unaddressed, so it is good but not fully complete for a listing tool.

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

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

Schema coverage is 0% and the lone 'folder' parameter is undocumented in the schema, so the description must compensate. It does: it specifies the expected format ('full name'), gives a concrete example ('Platform'), and defines the effect (list its immediate children), though the 'full name' vs returned 'full path' phrasing is slightly ambiguous.

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

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

States a specific verb and resource ('List jobs') with an explicit scope qualifier ('visible to this server, optionally within a folder'). It is easy to distinguish from get_job or list_running_builds by the scope, though it never names a sibling directly, so it falls short of a 5.

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

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

The description tells the agent exactly when and how to use the folder argument ('Pass a folder's full name, for example "Platform", to list its immediate children'), which is clear conditional guidance. It stops short of stating when not to use this tool in favor of a sibling such as get_job, so no explicit exclusions.

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

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

With no annotations, the description carries the full burden. It usefully discloses a scope boundary (executor/current-build data excluded) and hints that list_running_builds output is filtered through MCP_ALLOWED_JOBS, but says nothing about permissions, result size, or pagination for this call.

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

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

Two tight sentences, front-loaded with the core action and its returned fields, followed by the exclusion and the routing pointer. No filler.

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

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

For a zero-parameter read tool with no output schema and no annotations, the description supplies the essentials: what is listed, which fields matter, and what is deliberately omitted. Return shape and ordering remain unspecified, but that is a minor gap.

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

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

Zero parameters, so there is nothing to document; the schema trivially covers the empty argument object. Baseline 4 applies.

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

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

States a specific verb and resource ('List build nodes') and names the attributes returned (capacity, idle and offline state). It distinguishes itself from the builds-oriented sibling list_running_builds, though it does not contrast with the single-node sibling get_node.

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

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

Explicitly tells the agent what is out of scope ('Executor/current-build details are intentionally excluded') and routes to the named alternative ('use list_running_builds'). Clear condition for choosing the sibling, but no guidance on when list_nodes itself is preferred over get_node.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavioral traits: access scoping (jobs outside MCP_ALLOWED_JOBS are omitted) and payload truncation (plugin-specific executor/action payloads are not returned). It does not state ordering, volume limits, or that the call is a safe read, leaving gaps for an unannotated tool.

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

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

Three short sentences, each earning its place: what is listed, what is filtered, what to use next, and what is omitted. The core purpose is front-loaded with no filler.

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

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

There is no output schema, so the description must convey return shape, and it does (job and build number) while stating what is excluded from the payload. Minor gaps around result ordering and whether the list is paginated keep it from a 5 for an unannotated listing tool.

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

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

The tool takes zero parameters, so there is nothing to misinterpret and the baseline is 4. The description correctly implies an unfiltered, no-argument listing.

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

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

States a specific verb ('List') and resource ('builds currently executing') plus the scope ('across the controller') and the fields returned ('their job and build number'). This is clearly distinguishable from siblings like get_queue (queued vs executing) and get_build_console (following a single build).

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

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

Gives explicit routing advice: 'Use get_build_console to follow one,' which names the alternative and the condition that selects it. It also states a usage-relevant constraint (jobs outside MCP_ALLOWED_JOBS are omitted) but offers no other when/when-not guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose that this is a trigger (not a read) that causes branch discovery, but it omits meaningful side effects a caller needs, such as whether the scan may immediately kick off builds on newly found branches, what permissions are required, and whether the response is immediate or asynchronous.

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

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

A single well-formed sentence with the action front-loaded and a rationale clause; no filler or redundant restatement of the tool name.

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

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

For a one-parameter tool with no output schema and no annotations, the description covers the core action but leaves gaps: the lone parameter is unexplained, the return/behavior after triggering is unspecified, and the preconditions (e.g. that the job must actually be a multibranch pipeline) are unstated.

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

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

The single parameter job_name has no schema description (0% coverage) and the description never references it, so there is no added meaning about naming, required format, or whether it must reference a multibranch job specifically. With low coverage the description should compensate but does not.

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

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

The description names a specific action (trigger a branch scan) on a specific resource (a multibranch Pipeline), which cleanly separates it from sibling mutation tools like trigger_build or create_multibranch_pipeline. An agent can tell what this does 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.

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

The 'so newly pushed branches are discovered without waiting for the next scheduled scan' clause implies the scenario for using it, but there is no explicit when-not guidance or comparison against alternatives such as waiting for the scheduled scan or calling trigger_build. Usage is implied rather than stated.

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

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

With no annotations provided, the description carries the full disclosure burden and does so well: it labels the offline action destructive, explains the exact runtime effect on running vs new builds, and states the auth requirements (MCP_ALLOW_NODE_WRITE, plus MCP_ALLOW_DESTRUCTIVE for offline). This is the safety-relevant context an agent needs before mutating a node.

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

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

Front-loaded with the two-way action, followed by a compact paragraph on destructiveness and prerequisites. Nearly every sentence earns its place; the auth sentence could be tightened slightly, but there is no padding.

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

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

For a no-annotation, no-output-schema mutation tool, the behavioral side is complete — effects, risk level, and prerequisites are all stated. The remaining gap is parameter documentation (0% schema coverage), which an agent would need to supply from convention rather than the definition.

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

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

Schema description coverage is 0% for three parameters, so the description is the only source of meaning and it explains none of them. The boolean 'offline' is inferable from the prose, but node_name and message (with its 'Managed by MCP' default) get no explanation, leaving the agent to guess at the naming format and the purpose of the message field.

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

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

The description opens with a specific verb+resource pair ('Take a node offline, or bring it back online') that precisely names the state mutation this tool performs. It is trivially distinguishable from the read-only siblings list_nodes and get_node, so an agent can select it without inspecting schemas.

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

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

It clearly frames the offline branch as destructive and describes the operational consequence (running builds continue, no new work is scheduled, pipelines can stall), plus the required environment gates. It stops short of naming alternatives (e.g. use get_node/list_nodes to inspect state first), so it is clear context rather than explicit when/when-not routing.

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

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

With no annotations, the description carries the full burden and does so well: it flags destructiveness, the resulting ABORTED state, that completed work is lost, the mode escalation semantics, and the three required environment flags (MCP_ALLOW_BUILD_WRITE, MCP_ALLOW_DESTRUCTIVE, MCP_ALLOW_BUILD_STOP).

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

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

Front-loaded one-line summary followed by tightly packed constraints; every sentence adds operational information with no filler.

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

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

For a destructive mutation tool with no annotations and no output schema, the description covers effects, preconditions, and mode behavior well. Minor gaps remain, e.g., behavior when the build is already finished or per-job permission nuances.

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

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

Schema coverage is 0% and the schema gives mode only a default, so the description must compensate. It thoroughly explains mode (escalation and build-type restrictions), which is the non-obvious parameter; job_name and build_number are obvious by name but left undocumented.

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

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

Specific verb+resource in the first line: 'Stop a running build.' Clearly distinguishes itself from siblings like trigger_build, get_build_info, and cancel_queue_item.

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

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

Explains the mode escalation path (stop -> term -> kill) and the key constraint that Freestyle builds support only stop while term/kill are Pipeline-only and require workflow-job. It does not explicitly compare against siblings such as cancel_queue_item, so it stops short of a full routing guide.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that the return is a queue_id/queue_url rather than a build number, that the build has NOT started yet, and that an over-large encoded payload is rejected by MCP_MAX_REQUEST_BYTES. The remaining gap is permissions/auth requirements and whether a repeated trigger is deduplicated.

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

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

Front-loaded single-line summary followed by the operational detail, with no filler sentences. The detail paragraph is dense and run-on, but every clause (queue semantics, polling path, parameter rule, size limit) earns its place.

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

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

There is no output schema and 0% schema description coverage, yet the description names the returned fields and explains what they mean and do not mean. Combined with the polling guidance and parameter rules, an agent has everything needed to call this correctly and handle the result.

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

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

Schema coverage is 0%, so the description must compensate, and it does for `parameters`: default-vs-null semantics, the empty-object convention, and the size ceiling on the encoded form are all stated. `job_name` itself is left implicit, but its meaning is unambiguous from the tool purpose.

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

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

Opens with a specific verb+resource ("Queue a build") and immediately distinguishes itself from siblings by describing the queue-item lifecycle. An agent knows this is the trigger point, not a build-inspection tool, and is routed to get_queue_item / get_build_info as follow-ups.

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

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

Explicitly states the when and the follow-up sequence: poll get_queue_item until the executable has a number, then use get_build_info. It also gives a precise rule for parameterised jobs (pass an object, empty object for defaults, omitting makes Jenkins reject the trigger), which is a genuine usage discriminator.

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

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

With no annotations present, the description carries the full burden and does so thoroughly: it declares destructiveness, that no history is kept server-side, that omitted settings are lost, warns against plaintext credentials, and enumerates the three required environment flags plus the request byte limit. This is far beyond what the bare schema conveys.

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

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

Short, front-loaded, and every sentence carries distinct information: the operation, the destructive consequence, the pre-read step, the credential warning, and the authorization prerequisites. No filler or repetition of the tool name.

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

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

For a two-parameter destructive write with no output schema and no annotations, this covers the safety profile, preconditions, auth requirements, and size constraints an agent needs before calling. Nothing material is missing.

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

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

Schema description coverage is 0%, so the description must supply all parameter meaning. It does add useful semantics for config_xml (full replacement, omitted settings lost, size-bounded, no credentials), but job_name is never characterized and no format or validity constraints are given for either field.

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

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

States a precise verb and resource ('Replace a job's config.xml in full'), immediately distinguishing it from create_job_from_xml (creation) and get_job_config (read) in the sibling list. An agent knows exactly what operation this is 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.

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

Gives an explicit prerequisite workflow ('Read the current config first with get_job_config'), routing the agent to the correct companion tool before mutating. It does not explicitly say when to prefer this over create_job_from_xml or copy_job for cloning, but the 'in full' replacement framing makes the boundary clear enough.

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