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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the core action (create/update job) and mentions error handling ('Raises: JenkinsError'), but lacks details on permissions, side effects, rate limits, or what happens to existing job configurations. It adds some context but is incomplete for 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?

The description is well-structured with clear sections (Args, Returns, Raises) and front-loaded purpose. It is appropriately sized, but the inclusion of 'ctx' in Args, which is typically implicit in MCP, adds minor verbosity without significant value. Most sentences earn their place efficiently.

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

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

Given the complexity of a mutation tool with no annotations and no output schema, the description is moderately complete. It covers parameters and basic behavior but lacks details on return values beyond a generic 'Dict', error specifics, or operational constraints. It meets minimum viability but has clear gaps for full agent understanding.

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

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

The description provides detailed semantics for all parameters beyond the input schema, which has 0% description coverage. It explains what each parameter represents (e.g., 'Jenkins server name', 'Content of the Jenkinsfile'), clarifies optionality for 'description', and notes the purpose of 'ctx'. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states the specific action ('Create or update a Jenkins job') and the resource ('based on a Jenkinsfile'), distinguishing it from sibling tools like get_build_log or trigger_build which perform different operations. It precisely defines the verb and target without ambiguity.

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

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

The description implies usage through the phrase 'create if not exists, update if exists', suggesting when to use it, but does not explicitly state when to choose this tool over alternatives like search_jobs or validate_jenkins_config. No exclusions or prerequisites are mentioned, leaving some guidance gaps.

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 full burden for behavioral disclosure. While 'Get' implies a read operation, the description doesn't mention authentication requirements, rate limits, error conditions, or whether this retrieves full or partial logs. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

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

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

The description is efficiently structured with a clear purpose statement followed by parameter and return sections. Every sentence serves a purpose, though the parameter descriptions could be more informative. The front-loaded purpose statement makes the tool's function immediately apparent.

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

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

Given 3 parameters with 0% schema coverage and no annotations, the description is minimally adequate but incomplete. The presence of an output schema means return values are documented elsewhere, reducing the burden. However, for a tool that likely requires specific Jenkins knowledge and has behavioral implications, more context about authentication, error handling, and parameter formats would be beneficial.

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

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

The description lists all three parameters with brief labels, but schema description coverage is 0%, so parameters lack documentation in both schema and description. The description adds minimal semantic value by naming the parameters but doesn't explain what constitutes a valid 'server_name', 'job_full_name' format, or 'build_number' range, leaving them essentially 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?

The description clearly states the verb 'Get' and resource 'Jenkins build log', making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_build_status' or 'get_job_parameters' that also retrieve build-related information, so it doesn't reach the highest clarity level.

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

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

The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'get_build_status' and 'get_job_parameters' available, there's no indication whether this tool should be used for log retrieval specifically versus other build information, nor any prerequisites or exclusions mentioned.

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 of behavioral disclosure. It states the tool retrieves status but doesn't describe what 'Build status info' includes (e.g., success/failure, duration, timestamps), potential errors (e.g., invalid build number), authentication needs, rate limits, or whether it's a read-only operation. This leaves significant gaps for a tool with no annotation coverage.

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

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

The description is appropriately sized and front-loaded, with the core purpose stated first. The Args and Returns sections add structure, but the 'Returns' line is vague ('Build status info') and could be more informative. Overall, it's efficient with minimal waste, though slight improvements in clarity could enhance it further.

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

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

Given the tool's complexity (3 parameters, no annotations, no output schema), the description is incomplete. It lacks details on return values (beyond 'Build status info'), error handling, authentication, and how it differs from siblings. For a status retrieval tool in a Jenkins context, this leaves the agent with insufficient information to use it effectively without trial and error.

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

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

The description lists all three parameters (server_name, job_full_name, build_number) in the Args section, adding meaning beyond the input schema, which has 0% description coverage. However, it only names them without explaining semantics (e.g., format of job_full_name, range for build_number). This partially compensates for the schema gap but doesn't fully clarify parameter usage, aligning with the baseline for moderate coverage improvement.

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

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

The description clearly states the tool's purpose: 'Get the Jenkins build status for the specified build_number.' It specifies the verb ('Get'), resource ('Jenkins build status'), and scope ('for the specified build_number'). However, it doesn't explicitly differentiate from sibling tools like 'get_build_log' or 'get_job_parameters', which prevents a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_build_log' (for logs) or 'trigger_build' (for initiating builds), nor does it specify prerequisites or contexts for usage. The only implied usage is retrieving status, but no explicit alternatives or exclusions are 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 full burden for behavioral disclosure. It states this is a read operation ('Get'), but doesn't mention authentication requirements, rate limits, error conditions, or whether it's idempotent. For a tool accessing Jenkins parameters, this leaves significant gaps in understanding its behavior.

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

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

The description is perfectly structured: a clear purpose statement followed by organized Args and Returns sections. Every sentence adds value with zero redundancy, making it easy to parse and understand quickly.

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

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

Given the tool's moderate complexity (2 parameters, read-only operation), the description covers the essential purpose, parameters, and return format. The presence of an output schema means the description doesn't need to detail return values, but it still lacks behavioral context (auth, errors) that would make it fully complete.

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

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

The description explicitly lists both parameters (server_name and job_full_name) and explains their purpose, adding meaningful context beyond the schema (which has 0% description coverage). However, it doesn't provide format examples or constraints (e.g., job naming conventions), keeping it at baseline 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?

The description clearly states the verb 'Get' and the resource 'parameter definitions of a Jenkins job', making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from its siblings (like get_build_status or get_scenario_list), which would require 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing job), exclusions, or how it differs from sibling tools like search_jobs, leaving the agent to infer usage context.

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 of behavioral disclosure. It effectively describes what the tool returns (a list of scenarios with specific fields) and its role in the deployment workflow. However, it doesn't mention potential limitations like rate limits, authentication requirements, or error conditions, which would be helpful for a tool with no annotations.

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

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

The description is well-structured and front-loaded with the core purpose. Every sentence adds value: the first states the purpose and usage rule, the second explains the return value, and the workflow section provides actionable guidance. There's no redundant or wasted 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?

Given the tool has 0 parameters, an output schema exists, and no annotations are provided, the description is complete. It explains what the tool does, when to use it, what it returns, and how it fits into a broader workflow. The output schema likely covers the return structure, so the description doesn't need to duplicate that detail.

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

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

The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters, focusing instead on the tool's purpose and output. No additional parameter semantics are needed or provided.

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

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

The description explicitly states the tool's purpose: 'Get all available application scenarios' and identifies it as 'the preferred entry point for deployment tasks.' It clearly distinguishes this from sibling tools like 'search_jobs' by explaining this should be called first instead of directly using search_jobs. The verb 'get' and resource 'scenario list' are specific and unambiguous.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'For any deployment-related task, this function should be called first instead of directly using search_jobs.' It also outlines a complete workflow with specific sibling tools (search_jobs_by_scenario and trigger_build), giving clear context and 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 provided, the description carries the full burden of behavioral disclosure. It states the tool returns a list of server names, which is basic output information, but fails to describe critical behaviors such as whether this requires authentication, how the list is formatted (e.g., sorted, paginated), or any rate limits. For a tool with zero annotation coverage, this leaves significant gaps in understanding its operational traits.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a brief return statement. It avoids unnecessary elaboration, though the 'Returns:' section could be integrated more seamlessly. Overall, it is efficient with minimal waste, earning a high score for conciseness.

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

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

Given the tool's simplicity (0 parameters, 100% schema coverage, and an output schema exists), the description is adequate but not fully complete. It covers the basic purpose and return value, but lacks behavioral context (e.g., authentication needs, list characteristics) that would be helpful despite the output schema. For a read-only tool with no annotations, more disclosure would enhance completeness.

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

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

The tool has zero parameters, and schema description coverage is 100%, so there are no parameters to document. The description appropriately omits parameter details, aligning with the schema's completeness. A baseline of 4 is applied since no parameters exist, and the description does not need to compensate for any gaps.

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

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

The description clearly states the specific action ('Get the list') and resource ('all available Jenkins server names'), distinguishing it from sibling tools that focus on jobs, builds, parameters, or scenarios. It provides a precise verb+resource combination that leaves no ambiguity about its function.

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

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

The description implies usage when server names are needed, but offers no explicit guidance on when to use this tool versus alternatives (e.g., for server discovery vs. job-related operations). It lacks any mention of prerequisites, exclusions, or comparative context with sibling tools, leaving usage decisions 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 provided, the description carries full burden. It states this is a search operation but doesn't disclose behavioral traits like authentication requirements, rate limits, pagination behavior, or what 'matching jobs' means in practice. The description is adequate but lacks rich behavioral context.

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

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

The description is well-structured with clear sections (purpose, note, args, returns) and uses only essential sentences. The note about deployment tasks earns its place by providing valuable guidance. Slightly longer than minimal but appropriately so.

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

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

Given the tool has an output schema (so return values are documented elsewhere), 2 parameters with 0% schema coverage, and no annotations, the description provides good coverage: clear purpose, parameter explanations, usage guidance, and return type indication. It could benefit from more behavioral context but is reasonably 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?

With 0% schema description coverage, the description compensates by explaining both parameters: server_name specifies which Jenkins server, and keyword is the search term. This adds meaningful context beyond the bare schema, though it doesn't provide format examples or constraints.

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

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

The description clearly states the tool searches Jenkins jobs on a specified server, providing a specific verb (search) and resource (Jenkins jobs). It distinguishes from some siblings like get_build_log or trigger_build, but doesn't explicitly differentiate from search_jobs_by_scenario beyond the note about deployment tasks.

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

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

The description provides explicit guidance with a note recommending alternative tools (get_scenario_list and search_jobs_by_scenario) for deployment tasks. This gives clear context for when to consider alternatives, though it doesn't specify when NOT to use this tool or compare it to all siblings.

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 of behavioral disclosure. It mentions that it returns a 'List of job info matching the scenario,' which gives some output context, but lacks details on permissions, rate limits, error handling, or whether it's a read-only operation. For a tool with no annotations, this is insufficient.

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

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

The description is appropriately sized and front-loaded, with the main purpose stated first, followed by brief sections for Args and Returns. It avoids unnecessary details, but the structure could be slightly more polished (e.g., using bullet points). Overall, it's efficient with minimal waste.

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

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

Given the tool's moderate complexity, no annotations, and an output schema present, the description is partially complete. It covers the basic purpose and parameter semantics but lacks behavioral context and detailed usage guidelines. The output schema likely handles return values, so the description doesn't need to explain those, but it should address other gaps.

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

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

The description adds meaning by explaining that 'scenario' is a 'Scenario name or index,' which clarifies beyond the schema's generic 'string' type. However, with 0% schema description coverage and only one parameter, it compensates somewhat but doesn't provide examples, format details, or constraints, leaving room for improvement.

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

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

The description clearly states the tool's purpose: 'Get the specified Jenkins job directly by scenario.' It specifies the verb ('Get') and resource ('Jenkins job'), and distinguishes it from the sibling 'search_jobs' by focusing on scenario-based retrieval. However, it doesn't fully differentiate from 'get_scenario_list' which might list scenarios rather than jobs.

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

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

The description implies usage by specifying 'by scenario,' suggesting it should be used when you have a scenario name or index. It doesn't explicitly state when to use this tool versus alternatives like 'search_jobs' or 'get_scenario_list,' nor does it provide exclusions or prerequisites, leaving some ambiguity.

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 burden. It adds valuable behavioral context about 'intelligently handling permission errors' and 'automatically checking build status to confirm termination,' which goes beyond just stating the action. However, it doesn't mention important aspects like whether this is a destructive operation, what happens to queued builds, or error handling specifics.

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

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

The description is well-structured with clear sections (purpose, behavioral notes, args, returns) and uses only essential sentences. The front-loaded purpose statement is effective, though the 'Args' and 'Returns' sections could be slightly more detailed without sacrificing conciseness.

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

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

Given 3 parameters with 0% schema coverage and no annotations, the description provides basic parameter semantics and some behavioral context. However, for a mutation tool that stops builds, it lacks details on permissions, side effects, error scenarios, and the output schema's content ('Stop result' is vague). The presence of an output schema helps but doesn't fully compensate.

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

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

The schema description coverage is 0%, so the description must compensate. It lists all 3 parameters with brief explanations, which adds meaning beyond the bare schema. However, the explanations are minimal ('Jenkins server name,' 'Full job name,' 'Build number') and don't provide format examples, constraints, or relationship context.

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

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

The description clearly states the tool's purpose with a specific verb ('Stop') and resource ('Jenkins build'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_build_status' or 'trigger_build' beyond the obvious action difference.

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

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

The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, when not to use it, or how it relates to sibling tools like 'get_build_status' (which might be needed before stopping) or 'trigger_build' (which starts builds).

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 burden and does well by disclosing key behaviors: it automatically determines parameter requirements, waits to obtain a build number, and raises specific errors (JenkinsParameterError, JenkinsError). This covers operational traits beyond basic functionality, though it could add more on permissions or rate limits.

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

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

The description is well-structured and front-loaded with the core purpose, followed by organized sections for Args, Returns, and Raises. Every sentence adds value, such as explaining automatic parameter handling and error conditions, with no wasted words or redundancy.

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

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

Given the tool's complexity (triggering builds with parameter handling), no annotations, and an output schema present (so return values are documented), the description is complete enough. It covers purpose, parameters, behaviors, errors, and output, providing sufficient context for effective use without needing to repeat structured data.

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 lists all parameters (server_name, job_full_name, params, ctx) and explains their roles (e.g., 'Optional parameter dict', 'MCP context for logging'), adding meaningful context beyond the bare schema. However, it doesn't detail format or examples for params, leaving some gaps.

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

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

The description clearly states the action ('Trigger Jenkins job build'), the resource ('Jenkins job'), and distinguishes it from siblings like 'stop_build' or 'get_build_status' by focusing on initiating a build. It specifies the tool automatically determines parameter requirements and waits for a build number, making the purpose specific and differentiated.

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

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

The description implies usage for triggering builds and mentions automatic parameter handling, but does not explicitly state when to use this tool versus alternatives like 'create_or_update_job_from_jenkinsfile' or 'stop_build'. It provides clear context for build initiation but lacks explicit exclusions or comparisons to sibling tools.

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 of behavioral disclosure. It mentions the return value ('Validation result, including error list and status'), which adds some context about output. However, it lacks details on permissions needed, whether it's read-only or has side effects, error handling, or rate limits—critical for a validation tool in a Jenkins context.

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

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

The description is concise and front-loaded, stating the purpose in the first sentence and the return value in the second. There's no wasted text, but it could be slightly more structured (e.g., separating purpose and returns more clearly). Overall, it's efficient and to the point.

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

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

Given the tool's complexity (validation operation with no parameters) and lack of annotations and output schema, the description is minimally complete. It covers the purpose and return value, but for a Jenkins configuration tool, it could benefit from more context (e.g., what 'integrity' entails, example use cases). Without an output schema, the return description is helpful but basic.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details beyond the schema, but since there are no parameters, this is acceptable. It implies validation occurs on the overall Jenkins configuration without specifying inputs, which aligns with the empty schema.

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

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

The description clearly states the tool's purpose: 'Validate the integrity of Jenkins configuration.' It specifies the verb ('validate') and resource ('Jenkins configuration'), making the action clear. However, it doesn't explicitly differentiate from sibling tools like 'get_server_names' or 'search_jobs', which serve different purposes but are related to Jenkins operations.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., after configuration changes), exclusions, or how it relates to sibling tools such as 'trigger_build' or 'create_or_update_job_from_jenkinsfile'. Without this context, users must infer usage from the purpose alone.

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