mainframe-mcp-server

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful output shape ("rich 3-section report") and discloses that it extracts step/program/fix, but says nothing about behavior on edge cases — a job that succeeded, an unknown jobId, or spool-unavailable conditions — nor about cost or latency of the multi-step analysis.

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, front-loaded with the action and immediately followed by the concrete outputs. "Rich" is slightly promotional filler, but the rest of the text is dense and earns its place.

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

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

With no output schema, the description usefully compensates by naming the report contents and its three-section structure, which tells the agent what to expect back. What's missing is routing context within a large sibling set and any statement of prerequisites (e.g., needing a failed jobId first).

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 100%, with jobId, spoolDd, environment, and includeEvidence all documented in-schema, so baseline is 3. The description adds no parameter-level meaning, such as when to override spoolDd or how environment resolution interacts with list_environments.

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 ("Analyze a failed job") and enumerates the concrete artifacts produced (abend code, failing/cancelled step, program, suggested fix). It does not differentiate itself from closely related siblings such as find_failed_jobs, summarize_abends, lookup_abend_code, or analyze_root_cause, so an agent must infer which one fits.

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 is implied by "a failed job" — the agent can infer this is the deep-dive after a failure is identified — but there is no explicit when-to-use framing, no pointer to find_failed_jobs as the discovery step, and no exclusions against summarize_abends or analyze_root_cause.

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?

Adds real context beyond the annotations: the call actually submits a batch job and blocks waiting for it, and the parenthetical 'gated write' warns that write semantics apply even though destructiveHint is false. It does not explain what the gate requires (e.g., approve_write) or what happens if the wait times out, which keeps it below 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?

A single front-loaded sentence covering action, resource, wait behavior, and output, with the write caveat tucked in parentheses. 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?

For a 4-parameter, zero-required tool with annotations and no output schema, the description covers action, blocking behavior, write gating, and the kind of records returned. What's missing is the approval workflow precondition and timeout/failure behavior, which an agent would need before invoking.

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 100%, so all four parameters (report enum, environment, waitSeconds, logrecDataset) are already documented with defaults and bounds. The description only echoes the LOGREC dataset target and adds no format or interaction details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb chain (submit an EREP/IFCEREP report job, wait, summarize) against a named resource (the LOGREC dataset) and names the output domain (hardware/software error records). That is clearly distinct from siblings such as summarize_abends, analyze_job_failure, or read_dataset, which operate on different data sources.

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 is only implied: the mention of a 'gated write' hints that approval is involved, and 'wait for completion' implies a blocking call, but the description never says when to choose this over analyze_root_cause, summarize_abends, or investigate_incident, nor when not to use it.

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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that the analysis is 'deep' and 'AI-assisted' and enumerates the deliverables, but gives no sense of latency, cost, or data scope for what is presumably a heavyweight call, and there is no output schema to fall back on.

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 front-loaded sentence with no filler; every clause names a distinct output the agent will receive. Slightly list-like but efficient for the amount of information conveyed.

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?

Because no output schema exists, the enumeration of returned artifacts is genuinely useful. But for an AI-driven analysis call sitting among several overlapping analysis siblings, the definition leaves the agent without selection criteria or any hint of cost/duration, so it is only adequate, not complete.

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

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

Schema description coverage is 100%: jobId format, environment lookup via list_environments, and lookbackHours default/max are all documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 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 ('Deep AI-assisted root-cause analysis') and enumerates what it produces: failure details, abend reference, incident correlation, health score, action items. However, it draws no boundary against the near-identical siblings analyze_job_failure and investigate_incident, so an agent cannot tell from the description which analysis tool to pick.

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?

There is no when-to-use guidance at all. With three overlapping failure-analysis siblings in the toolset, the absence of any routing rule or prerequisite (e.g., 'run after get_job_status confirms failure') is a meaningful gap; only the required jobId parameter implicitly signals it applies to a failed job.

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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the risk profile is covered. The description adds genuinely new context: the human-in-the-loop gate, the one-time token, and the SECURITY_WRITE_APPROVAL environment condition. It stops short of describing what happens on token expiry or failure, hence not a 5.

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

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

Two compact sentences with zero filler; the core action is front-loaded and the prerequisite/environment gate follows immediately. Every clause 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 2-parameter mutation with no output schema and annotations covering the risk profile, the description supplies the essential gate conditions and token origin. It could say more about failure modes (invalid/expired token) but is otherwise sufficient to invoke correctly.

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

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

Schema coverage is 100% and both parameters (token, environment) are documented in the schema, so the schema carries the load. The description only reinforces that the token originates from submit_jcl, adding marginal value beyond the existing field description. Baseline 3.

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 ('Approve and execute a pending JCL submission') and adds the human-in-the-loop qualifier that distinguishes it from submit_jcl and the many read-oriented siblings. An agent can separate it from submit_jcl without opening either schema.

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

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

Explicitly names the prerequisite ('Requires the one-time token from submit_jcl') and the activation condition ('active only when SECURITY_WRITE_APPROVAL=true'). This routes the agent to submit_jcl first and tells it when this tool is available at all.

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?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds 'gated write,' which usefully signals that approval or gating may be required. However, it does not explain what happens to the job, whether cancellation is reversible, or how gating works in practice.

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 front-loaded sentence with no wasted words. The core action and scope are immediately clear.

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

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

The tool is simple with two parameters covered by the schema and safety traits covered by annotations. The description is adequate but leaves gaps around gating mechanics and post-cancellation behavior, which matter for a destructive write operation.

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

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

Schema description coverage is 100%, and both parameters are fully documented in the schema. The description adds no parameter-specific meaning beyond the schema, which is the baseline case for full coverage.

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

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

States a specific verb and resource: cancel a running or queued job. The scope (running or queued) is clear. It does not explicitly differentiate itself from sibling lifecycle tools like hold_job or release_job, so it stops 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 phrase 'running or queued job' implies when the tool applies, but there is no explicit when-not guidance or named alternative. An agent can infer usage from the verb and resource, but the routing guidance is only implied.

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?

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds genuinely new semantics — that this is a gated write and that in-flight tasks are allowed to complete rather than being killed. It does not explain what the gate is (e.g. whether approve_write must be called first) or what the response contains, so it stops short of full disclosure.

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?

One compact sentence with the verb and resource front-loaded, followed by the scope note and the in-flight-tasks caveat. No filler, and the most decision-relevant facts come first.

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?

Adequate for a 5-parameter mutation tool: annotations carry the destructive/idempotent profile, the schema documents every parameter, and there is no output schema to explain. The only real omission is the unresolved meaning of 'gated write' and what the tool returns on success.

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 100%, so all five parameters, including the enable-inversion behavior, are already documented in structured form. The description restates the ENABLESTATUS mapping without adding format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

A specific verb and resource — 'Disable a CICS local transaction' — plus the exact CMCI mechanism (SET with ENABLESTATUS=DISABLED). The schema's enable flag is echoed, so an agent can tell this apart from list_cics_transactions or cics_newcopy immediately.

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?

'New work is refused; in-flight tasks finish' implies the operational reason to use it (quiescing a transaction) but never states when to choose it over alternatives or when not to use it. 'Gated write' hints at a prerequisite step without naming it, leaving the agent to infer how the gate is satisfied.

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?

Annotations already declare a non-read-only, non-idempotent, non-destructive write, so the bar is lower. The description still adds non-obvious context: that the write is gated (needs approval), and that it requires CMCI actions support on CICS TS 5.6+, which an agent cannot infer from the schema. It does not say what happens to in-flight tasks during the phase-in, which is the main remaining behavioral gap.

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 front-loaded sentence carrying the action, its semantics, the mechanism, and the prerequisite, with no filler. Every clause earns its place.

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

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

No output schema exists, and while parameters and safety hints are covered, the description leaves the 'gated write' mechanic unresolved: it never says whether the agent must first obtain approval (e.g., via approve_write) or what a successful NEWCOPY reports back. For a write action that affects a running production region, that is a material omission.

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 100% across all four parameters, including the environment pointer back to list_environments, so the schema already does the work. The description contributes no additional parameter meaning, which is the expected baseline when coverage is complete.

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 (NEWCOPY) and resource (a CICS program), and parenthetically defines the jargon as a 'phased-in fresh copy', which is genuinely useful. It also notes the mechanism (CMCI resource action), distinguishing it from console-driven or transaction-level siblings like cics_disable_transaction, though it never names a 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?

Gives a real prerequisite ('Requires CMCI with actions enabled (CICS TS 5.6+)') and flags it as a 'gated write', implying the approval flow, but never states when to choose this versus other remediation actions or what the gating step actually is. Usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and idempotency profile is fully covered. The description adds the scope of what is compared (status, return code, failure indicators), but says nothing about behavior for missing jobs, mixed-environment comparison, or environment defaulting. Adequate but not rich, given annotations carry the main burden.

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 front-loaded sentence with the compared fields enumerated immediately and no filler. Every clause 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 read-only comparison tool with a fully-documented schema and annotations covering safety and idempotency, the description says enough to call it correctly: which two IDs, optional environment, and what is compared. The only minor gap is how it behaves with invalid or cross-environment job IDs, which is not stated.

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 100%, so all three parameters (jobId1, jobId2, environment) are already documented in the schema, including the pointer to list_environments for the environment parameter. The description adds no format or syntax detail beyond the schema, so the baseline of 3 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 (compare) and resource (two jobs) plus the exact fields it reports on: status, return code, and failure indicators. This is clearly distinguishable from get_job_status or analyze_job_failure, which handle one job or failure analysis, not side-by-side diffing.

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 phrase 'side by side' implies the comparison use case, but there is no explicit guidance on when to prefer this over calling get_job_status twice, nor any mention of prerequisites or when not to use it. Usage must be inferred from the name and description alone.

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?

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety bar is low, and the description adds real context by disclosing that prices derive from the CAPACITY_MSU_RATING and MLC_MSU_MONTHLY_PRICE configuration values — telling the agent results are config-dependent. It stops short of saying what happens when those configs are unset or what the returned estimate looks like.

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: the capability is front-loaded and the pricing-source caveat follows as supporting context. Nothing is redundant with the name or title.

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, the description carries the burden of describing the return, and it never says whether the result is a dollar figure, a cost breakdown, or an MSU-to-cost mapping. It also leaves the all-parameters-optional situation (nothing can be estimated without jobId, cpuSeconds, or msuConsumed) unaddressed, though annotations and the rich schema cover most of the rest.

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 100%, so all four parameters are already fully documented, and the description does not elaborate beyond the schema. It implies the CPU-vs-MSU choice but adds no format, unit, or precedence detail for the mutually exclusive inputs, nor mentions the optional `environment` parameter. 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 and resource ("Estimate MLC cost attribution") and names the two measurement bases it accepts (CPU seconds or MSU consumption), which maps directly onto the schema's numeric inputs. It is immediately distinguishable from the job/CICS/DB2 siblings, none of which deal with cost, though it does not explicitly say so.

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 is implied by the two input modes, and the schema documents that jobId is mutually exclusive with the numeric inputs, but the description itself offers no when-to-use guidance, no prerequisites, and no routing to any alternative sibling.

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?

Annotations already establish readOnly, idempotent, non-destructive, open-world behavior. The description adds one useful behavioral fact beyond that: results are summarized by abend/step rather than returned as raw job records. It still says nothing about result limits, grouping, or whether the summary is aggregated counts or per-job lines.

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 front-loaded sentence with no filler; the scope (recent window) and the output shape (abend/step summary) both land immediately.

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 all parameters optional and no output schema, the description could clarify what the summary looks like (grouped counts vs. per-job entries) and whether there are result caps. Annotations cover safety, so this is adequate but not complete for a summarization tool whose return shape is unspecified.

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 100% – hours, owner, and environment all have descriptions including defaults and the list_environments pointer. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('find all failed jobs') plus an output behavior ('summarize their abend/step'), and the time-window scoping is clear. It does not explicitly differentiate from close siblings like analyze_job_failure or summarize_abends, so it stops 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?

There is no when-to-use / when-not-to-use guidance and no named alternative. An agent must infer that this is the bulk-failure lookup versus per-job tools like get_job_status or analyze_job_failure.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value by noting fields are release-dependent ('your CMCI release provides'), which warns the agent not to assume a fixed field set. It says nothing about size of response, error behavior when the region is unknown, or CMCI connectivity 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?

A single front-loaded sentence with a useful parenthetical; no boilerplate, no repetition of the tool name, nothing that could be cut.

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 three-parameter read tool with no output schema, the description hints at return contents (uptime, task counts) but explicitly declines to pin them down, leaving the agent unable to predict the response shape. The more serious omission is disambiguation from get_cics_region_status, which is the main correctness risk here.

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 100% and all three parameters carry inline descriptions (APPLID, CMCI context, named environment), so the schema does the heavy lifting. The description adds no meaning beyond the schema — it does not clarify how 'context' interacts with 'environment' or what happens when both are supplied.

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?

Names a specific resource and source (CICS region statistics from the CMCI CICSRegion resource) and enumerates representative fields (uptime, task counts). However, it does not distinguish itself from the near-identically named sibling get_cics_region_status, so an agent cannot tell from the description alone which to call.

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?

There is no statement of when to use this tool, when not to, or how it relates to get_cics_region_status, list_cics_regions, or list_environments. The only hint is the 'environment' parameter's parenthetical pointing at list_environments, which is schema text, not description 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?

Annotations already cover read-only, idempotent, non-destructive, and open-world behavior, so the safety profile is clear. The description adds that data is fetched via CMCI and names the returned fields, but does not disclose failure behavior, authentication needs, 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?

A single efficient sentence front-loads the action and resource with no filler. Every part of the sentence contributes to identifying the operation.

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 low-complexity read tool with fully documented parameters and rich annotations, the description is almost complete. It names the returned fields, though it could say more about output shape or error conditions since no output schema exists.

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 100%, so all three parameters are already documented in the schema. The description only refers generally to a 'CICS region' and adds no syntax or semantics beyond the schema.

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

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

The description states a specific verb and resource: retrieving current status, version, and attributes of a CICS region. It is clearly distinct from list-oriented siblings, though it does not explicitly contrast itself with get_cics_region_stats or list_cics_regions.

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 is implied by 'current status, version, and attributes of a CICS region via CMCI,' but the description never states when to use this over list_cics_regions or get_cics_region_stats. There are no explicit alternatives or 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context with 'operations-log tail,' 'unsolicited,' and 'SYSLOG-style feed,' but it does not describe return format, rate limits, or pagination 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 a single, front-loaded sentence with no filler. It states the core operation and the data source 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?

For a simple read-only tool with three fully documented optional parameters and complete safety annotations, the description is nearly sufficient. It identifies the feed type and tail semantics, though it leaves usage routing and return shape implicit.

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 100%, so maxLines, consoleName, and environment are already documented in the schema. The description does not add parameter-level meaning beyond what the schema provides, so the 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?

The description gives a specific verb and resource: 'Read the operations-log tail' and 'recent unsolicited console messages ... from an extended MCS console.' It is clearly a read-only console-feed operation, which distinguishes it in practice from issue_console_command, but it does not explicitly name that sibling alternative.

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 purpose implies when the tool is useful: when an agent needs recent unsolicited console messages. However, the description gives no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling diagnostic 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, so the safety profile is covered; the description adds the meaningful behavioral fact that no records are read and that member summary is an optional extra limited to PDS/PDSE. It does not describe failure behavior for a missing dataset or RACF authorization errors, which would be the next useful detail.

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

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

Two sentences, zero filler, with the core purpose and the returned attribute list front-loaded. Every clause carries information the agent needs.

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, yet the description compensates by naming the catalog attributes returned, which is exactly what an agent needs to decide between this and read_dataset. Minor gap: no mention of error/not-found handling or that some attributes are blank for non-VSAM datasets.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description's mention of the optional member summary largely restates includeMembers' schema text. Baseline 3 applies since there is no added syntax or format guidance beyond the schema.

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

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

Specific verb (Get) plus resource (catalog attributes for a dataset) and an explicit enumeration of returned fields (DSORG, RECFM, LRECL, BLKSIZE, volume). The phrase 'without reading its content' cleanly separates it from read_dataset in the sibling list.

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 'without reading its content' clause implicitly routes the agent here when only metadata is needed rather than a full read, and the PDS/PDSE qualifier scopes includeMembers. It stops short of explicitly naming read_dataset/search_dataset as the alternative for content or name lookups, and states no prerequisites for dataset access.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds genuinely useful context that results are 'filtered from the operations-log tail', implying a limited recent window rather than full history, but it never defines 'recent' or says whether older activity is reachable.

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 front-loaded sentence with no filler; the resource and its scoping constraint come first and 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?

For a zero-required-parameter read tool with full schema coverage and rich annotations, this is nearly sufficient: the agent knows the source (log tail), the content (HSM events), and the volume control (maxLines). A note on return format or the effective time window would close the last 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?

Schema description coverage is 100% — maxLines, consoleName, and environment are all documented in-schema, including the default and env-var fallback. The description adds nothing about parameters, so baseline 3 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?

Names the specific resource (DFSMShsm activity) and enumerates the activity subtypes (recalls, migrations, backups), plus the source (operations-log tail). This clearly separates it from generic log/console siblings like get_console_messages or analyze_logrec, though it never names an alternative explicitly.

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

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

The use case is implied by the subject matter — reach for this when you need HSM-specific events rather than raw console traffic — but the description never states when to prefer it over get_console_messages, analyze_logrec, or system_health_summary, nor any prerequisites.

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?

Annotations already cover read-only, idempotent and non-destructive semantics, and the description adds real value on top: it discloses the data source (JESMSGLG, IEF374I/IEF376I) and the fact that MSU figures only appear when CAPACITY_MSU_RATING is configured. It stops short of saying what happens when those log records are missing or the job's JESMSGLG has been purged.

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 front-loaded sentence that carries the source, the specific message IDs and the conditional behaviour with no filler. Every clause is load-bearing.

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 only two parameters, full schema coverage and no output schema, the description does a fair amount of return-value work by previewing the shape (per step, total, optional MSU estimate). A note on behaviour when the log records are absent is the main remaining 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?

Schema description coverage is 100% — jobId and environment are both documented inline, including the pointer to list_environments. The description adds nothing about either parameter, so this sits at the baseline where the schema does all the work.

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?

Names a specific resource (CPU consumption of a job) and scopes it precisely to per-step and total figures, plus a conditional MSU estimate. It is distinctive enough that an agent can separate it from get_job_status or get_job_output, though it never explicitly names those siblings as alternatives.

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?

There is no when-to-use, when-not-to-use, or alternative-naming guidance. The description never tells the agent to prefer estimate_mlc_cost for cost figures or get_job_output for raw log text, so routing must be inferred from the noun phrase alone.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the spool-source detail (JESJCLIN/JESJCL/JCL DDs), which is genuinely useful context, but says nothing about truncation behavior, missing/purged JCL, or permissions.

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, front-loaded with the purpose before the caveat. The trailing 'Supports custom line limit' is largely redundant with the schema, keeping it just below a 5.

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

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

For a simple, read-only, 3-parameter tool with annotations covering safety, this is nearly complete. The remaining gap is that no output schema exists and the description doesn't say what the return looks like (raw JCL lines vs. array) or what happens when JCL is unavailable.

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 100%, so jobId, maxLines and environment are already documented, including the server-configuration cap. The description's 'Supports custom line limit' only restates what the schema says, adding no new semantics; baseline 3 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 (Retrieve) and resource (the JCL submitted for a job), and even names the spool data sets it reads from (JESJCLIN / JESJCL). It is clearly distinct from get_job_output, though it does not explicitly say so.

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 is implied — an agent would infer 'call this when you need the submitted JCL rather than job output' — but there is no explicit when-to-use, no exclusion, and no pointer to get_job_output or get_job_status as alternatives.

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?

Annotations already declare readOnly, idempotent, non-destructive, openWorld behavior, so safety is covered. The description adds real behavioral detail beyond that: two distinct return shapes, step filtering only in list mode, and that grep is applied before line capping — an ordering nuance that affects results.

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

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

Two sentences, front-loaded with the core verb and resource, then the dual-mode breakdown. No filler and nothing redundant given 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?

With no output schema, the description does cover return shape at a high level (spool file list vs. DD content). It could say more about pagination/truncation signals when maxLines caps output, but it is sufficient to call the tool correctly.

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

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

Schema coverage is 100%, so all six parameters already carry descriptions including the grep-before-cap ordering and the stepName-only-when-ddName-omitted rule. The description restates these semantics rather than adding new meaning, so the baseline 3 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?

The description states a specific verb (Retrieve) and resource (spool output for a job) and clearly enumerates the two operating modes: listing spool files vs. returning one DD's content. An agent can distinguish this from siblings like get_job_jcl or read_dataset 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 mode selection is clear: omit ddName to list spool files, supply ddName to read one DD, with stepName only applying in listing mode. It doesn't name alternative tools (e.g., compare against get_job_jcl) or state when-not-to-use, so it falls just short of 5.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful content beyond that: it specifies the exact return payload and that spool inventory is opt-in, which tells the agent the call is cheap by default.

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

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

Two short sentences with the primary payload front-loaded and the optional behavior trailing. Nothing is wasted and nothing important is buried.

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, the description carries the burden of describing return values, and it does so by enumerating status, return code, failure indicator, and optional spool inventory. It stops short of noting not-found behavior or how the failure indicator should be interpreted, which keeps it off a 5.

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 100%, so the baseline is 3. The phrase 'optionally includes spool file inventory' loosely restates the includeSpoolSummary schema text but adds no format or interaction detail beyond it, and jobName/environment are untouched in the 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 uses a specific verb (get) plus resource (job status) and names the concrete fields returned: status, return code, failure indicator. This differentiates it implicitly from siblings like get_job_output or list_jobs, though it never names an alternative explicitly.

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

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

Naming 'a specific job' implies this is the per-job lookup rather than a listing, so usage is inferable. But there is no statement of when to prefer this over get_job_output or analyze_job_failure, and no prerequisites 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing the dual data sources (live z/OSMF RMF and/or a configured SMF summary dataset), implying fallback behavior, but says nothing about result volume, pagination, or what happens if neither source is available.

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, front-loaded with the core action and resource, with the filtering note appended. No filler, though it is on the terse side for a tool with multiple data sources.

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, the description does not indicate what the returned metrics look like (structure, units, volume), and it omits any mention of the need for a configured SMF dataset or a working z/OSMF connection. Adequate to select the tool, but thin for invoking it confidently.

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 100% and both parameters carry self-explanatory descriptions, so the baseline is 3. The description's 'Supports category filtering' only restates the category parameter without adding format or default details beyond the schema.

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

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

Specific verb (Retrieve) plus resource (SMF/RMF performance metrics) and the data sources (z/OSMF RMF and/or SMF summary dataset). It is clearly distinct from every sibling tool, which are job/CICS/DB2/dataset oriented, though it does not explicitly name a sibling to contrast with.

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 statement of when to use this instead of alternatives such as system_health_summary or get_wlm_status, and no prerequisites mentioned (e.g. z/OSMF connection, dataset configuration). The only guidance is the passing note about category filtering.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety behavior is covered. The description adds the status categories included in the summary, but it does not describe return shape, aggregation semantics, or how the optional prefix/environment filters affect the counts.

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 front-loaded sentence with zero waste. It states the action, scope, and included statuses without boilerplate.

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

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

For a simple read-only summary tool with full schema descriptions and safety annotations, the description is largely complete. It could add a little about what the summary returns, but the core behavior is clear enough to invoke 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 100%, so the schema already documents owner, prefix, and environment fully. The description reinforces the owner scoping and status categories but adds no syntax or behavior beyond the schema baseline.

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 (summarize) and resource (job counts by status) scoped to a specific owner. It is clear enough to distinguish from listing or status-detail tools, though it does not explicitly name sibling alternatives.

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 when-to-use guidance, no exclusions, and no alternative tools such as list_jobs or get_job_status. An agent must infer that this tool is for aggregate counts rather than job details.

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?

Annotations already cover the read-only, idempotent, non-destructive safety profile. The description adds useful behavioral context by naming the z/OSMF Storage Management Interface and disclosing the STORAGE_FREE_THRESHOLD default of 10%.

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

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

The description is two sentences, front-loaded with the core purpose and then the threshold behavior. There is no redundant or wasted text.

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

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

The description is mostly complete for a simple two-parameter read-only inventory tool, especially because annotations cover safety and the schema covers inputs. It could be slightly stronger by explicitly noting that the result is a per-volume space inventory, but the core behavior is clear.

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 100%, and both parameters are already well documented in the schema. The description does not add parameter-specific meaning beyond that, so the baseline of 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?

The description states a specific resource and action: DASD volume space inventory, with the added behavior of flagging volumes below a free-space threshold. It is clearly distinguishable from sibling tools such as dataset, job, and CICS 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 use case is clear from 'DASD volume space inventory' and the low-free-space flagging behavior. However, it does not explicitly state when to use this versus alternatives or any when-not conditions.

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?

The annotations already flag readOnlyHint=false and openWorldHint=true; the description adds the missing explanation of why — a real console command is issued and the path is a "gated write", which tells the agent to expect approval/side-effect semantics. It stops short of saying whether approval is required (e.g. via approve_write) or what happens to the target system.

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 dense sentence that front-loads the action, the resource, and the execution mechanism, with the side-effect caveat parenthetically attached. Nothing 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 3-param, no-required-argument tool with full schema coverage and annotations covering the safety profile, the description supplies enough to call it correctly. The only gap is that with no output schema, the agent is not told that the result is raw console output text for the WLM display.

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 100% — every parameter (command, consoleName, environment) is documented with defaults and examples. The description adds only the default "D WLM" shape already present in the schema, so baseline 3 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 (Display) and resource (Workload Manager state) plus the exact mechanism (MVS "D WLM" console command), so the agent knows precisely what it retrieves. It does not explicitly differentiate itself from the generic issue_console_command sibling, which would be the natural alternative for this same request.

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 phrase "gated write: a console command is issued" hints at why this exists separately from raw console commands, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. issue_console_command for arbitrary commands). Usage must be inferred from the description of the operation.

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?

Annotations already declare a non-read-only, non-idempotent, non-destructive, open-world operation. The description adds useful behavioral detail beyond that: the operation uses the JES2 $HJ command, is a gated write, and takes effect at the next step boundary.

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 tightly written sentences with no waste. The core action and command are front-loaded, followed immediately by the timing behavior.

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

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

For a simple action tool with full schema coverage and meaningful annotations, the description is nearly complete. It covers the action, command, gated nature, and effect timing; it could go slightly further in explaining what the gate entails or linking to approve_write.

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 100%, so all three parameters (jobId, consoleName, environment) are already documented in the schema. The description does not add parameter-specific semantics beyond what the schema provides, so the baseline of 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 and resource (hold a batch job) and identifies the underlying JES2 $HJ command. It is clearly distinguishable from siblings like release_job, cancel_job, and submit_jcl.

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 when to use the tool by saying it holds a job and stops at the next step boundary, but it does not explicitly contrast this with release_job or cancel_job. 'Gated write' hints at an approval requirement without explaining when that gate applies.

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?

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotency, so the safety profile is covered. The description does add one genuinely new behavioral fact — that writes are 'gated' — but it never explains how the gate works (is approve_write required first? what happens on rejection?), nor what the command can affect on a live IMS system.

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, front-loaded with the action and the console routing, with no filler. The three example commands are mildly redundant with the schema example but serve as a quick syntax anchor, so the cost is small.

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, open-world write tool with no output schema this is thin: it never says what an agent must do to satisfy the 'gated' requirement, what a rejection looks like, or how follow-up messages relate to collectKey. Parameter documentation is fully handled by the schema, but the operational flow around the gate 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 100%, so all four parameters are already documented, including the slash-normalization rule and the collectKey follow-up mechanism. The description's command examples and slash prefix note largely restate the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (issue an IMS command) and the channel it flows through (z/OS system console), which is more than the bare name conveys. It does not distinguish itself from the sibling issue_console_command, so an agent cannot tell from this text alone which console-facing tool to pick.

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 parenthetical '(gated write)' implies the tool is behind an approval flow, and the three example commands sketch the intended use. But there is no explicit when-to-use / when-not-to-use guidance and no pointer to the alternative issue_console_command or to approve_write, leaving the choice 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered; the description adds concrete value by disclosing the composite output (RCA with abend reference and runbook link, RAG doc excerpts, full spool inventory, per-DD diagnostic excerpts). It does not warn that this is a heavyweight multi-source call, which is the main remaining gap.

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

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

A single front-loaded sentence that names the action, the scope and the bundle contents with zero filler. The parenthetical additions (abend reference, runbook link, RAG) are informative rather than repetitive.

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, the description carries the burden of describing the return surface and does so by enumerating every bundle section. Adequate for a 3-parameter read-only tool, though it omits any note about latency/cost of gathering all sources or the excerpt-size default.

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 100%, so jobId, environment and maxExcerptLines are fully documented in the schema. The description adds nothing parameter-specific (e.g. that omitting environment targets the server default, or that maxExcerptLines bounds each excerpt), so baseline 3 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?

Specific verb ('Assemble') plus resource ('full incident bundle for a job') with an enumerated inventory of what the bundle contains (status, RCA, RAG excerpts, spool inventory, DD excerpts). It reads as an aggregator, but the description never contrasts it with the overlapping siblings analyze_job_failure and analyze_root_cause, so an agent must infer the boundary.

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 is only implied by the word 'full' and 'Assemble' – the description suggests a deep, one-shot investigation, yet it gives no explicit when-to-use/when-not and names no alternatives among the many diagnostics siblings. Minimum viable routing 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?

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, so the risk profile is known. '(gated write)' adds real context about the approval gate, but the description does not say what an arbitrary operator command can affect or how responses are collected if collectKey is omitted. Notably, all three examples are display ('D ...') commands, which can understate the destructive capability the annotations flag.

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

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

Two sentences, front-loaded with the verb and resource, with the examples trailing as supporting detail. No wasted words.

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

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

For a 4-parameter destructive tool with no output schema, the description covers purpose and the gating concept but not the response-collection workflow (collectKey) or the MVS-vs-IMS vs get_console_messages routing. Adequate but with clear gaps an agent would have to resolve from the schema alone.

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 100%, so every parameter (including collectKey, consoleName, environment) is already documented in the schema. The description's examples coincide with the schema's own example for `command` and add no new semantics. Baseline 3 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 ('Issue'), a specific resource ('MVS system/operator command'), and the mechanism ('extended MCS console'), plus three concrete command examples. An agent can distinguish this from get_console_messages (read) and ims_command (IMS) without opening a 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 command examples imply when this is appropriate, and '(gated write)' hints at an approval prerequisite, but the description never names an alternative (e.g., get_console_messages for reading, ims_command for IMS) or states exclusions. Usage guidance is suggested 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds what the analysis operates on (datasets and PROCs per step) but says nothing about the spool-read behavior when a jobId is used, latency, or failure modes for malformed JCL — context the annotations do not supply.

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 sentence, front-loaded with the verb and resource, with every clause (inputs, outputs, updates per step, PROCs) contributing distinct information. No filler or restatement of the 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?

No output schema exists, but the description effectively pre-announces the return content by listing the dependency categories that will be reported. With all three parameters optional and a well-covered schema, this is nearly complete; only the response shape (per-step nesting, empty-result behavior) is 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 description coverage is 100%, with mutual exclusivity of 'jcl' and 'jobId' and the purpose of 'environment' already documented in the schema. The description adds no syntax, format, or defaulting detail beyond the schema, so the baseline of 3 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?

Names a specific verb (analyze) and resource (a job's JCL) and enumerates exactly what is extracted: dataset inputs, outputs, updates per step, and PROCs invoked. That enumeration separates it from siblings like get_job_jcl (raw retrieval) or analyze_job_failure (failure diagnosis), though it never names those alternatives 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 trailing clause 'the basis for predecessor/successor analysis' implies the downstream use case, but there is no explicit when-to-use, when-not-to-use, or alternative named among the many job-related siblings. The agent must infer that this is the pre-analysis step before prediction/scheduling work.

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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds that filtering and capping are supported, but says nothing about whether results span one context or all environments, how capping interacts with filtering, or what happens when the context is omitted.

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, front-loaded with the resource and scope, and each sentence carries information. It is efficient, though the terseness leaves real behavioral questions unanswered rather than deliberately trimmed.

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

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

All four parameters are optional and fully documented in the schema, and there is no output schema to explain. Still, for a tool whose environment/context parameters can materially change which regions are returned, the description omits how those defaults resolve and what the listing looks like.

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 100%, so the baseline is 3. The description echoes the status filter and maxResults cap but adds no syntax, defaults, or interaction detail beyond the schema, and does not touch the context or environment parameters at all.

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 CICS regions") plus scope ("in a CMCI context"), which is unambiguous. However it does not distinguish itself from close siblings like get_cics_region_status, get_cics_region_stats, or list_cics_transactions, so an agent gets the what but not the why-this-one.

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 is only implied by the mention of a status filter and result capping; there is no explicit when-to-use, when-not-to-use, or named alternative such as get_cics_region_status for a single region or list_environments for target selection. The agent must infer routing from tool names alone.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that results come from CMCI and can be capped, but says nothing about pagination, truncation warnings, or the shape of a transaction entry.

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 core action front-loaded and zero filler. It is efficient, though it stops short of any routing or constraint information that would make it exemplary.

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 read-only filtered list with full schema descriptions, complete annotation coverage and no output schema, the description supplies the essential mechanism (CMCI) and filter/cap behavior. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, with each of the 6 parameters documented including examples and env-var fallback. The description only gestures at 'prefix/status filters and result capping', which maps to tranPrefix, status and maxResults but adds no syntax or behavior beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List CICS transaction definitions') plus the retrieval mechanism and scope ('installed in a region via CMCI'). It is clearly distinguishable from siblings like get_cics_region_status or cics_disable_transaction, though it never names an alternative explicitly.

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

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

The mention of 'prefix/status filters and result capping' implies when the filters are useful, but there is no explicit when-to-use guidance, no exclusions, and no reference to sibling tools such as list_cics_regions or get_cics_region_stats.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds only that filtering and count-capping are supported, and it does not explain what the result set looks like (names only? with attributes?) or how the 'server limit' truncation manifests.

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, front-loaded with the resource and the qualifier scoping, then the optional capabilities. Nothing is redundant, though the second sentence is a feature list rather than guidance.

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, the description should say what a returned dataset entry contains and how truncation/pagination surfaces, and it doesn't. It says enough to invoke the tool but leaves the result shape and any limit behavior implicit.

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 100%, and every parameter the description mentions (hlq, pattern, dsorg, maxResults) is documented in more detail in the schema, including the enum meanings. The description adds no syntax or interaction detail beyond that baseline.

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 (list catalog datasets) and the scoping mechanism (high-level qualifier plus optional pattern), which is more concrete than the bare name. It does not, however, distinguish itself from the sibling search_dataset, so an agent can't tell from the description which of the two to pick.

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?

There is no statement of when to use this tool versus search_dataset, search_members, or get_dataset_info, and no prerequisites or exclusions. The only hint is that it enumerates by qualifier, which the reader must infer is the difference from the search 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral fact — the DB2_LOCATION prerequisite — but says nothing about the open-world nature of the call (live subsystem discovery) or failure behavior when DB2_LOCATION is unset.

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?

One short sentence, front-loaded with the purpose and ending with the key prerequisite. No waste, though 'requires DB2_LOCATION' is terse enough to be slightly cryptic about what the variable controls.

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

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

For a simple, annotation-covered read-only lister with a single fully described optional parameter, the description plus structured fields are sufficient to call it correctly. Only the shape of a returned subsystem/location entry is left implicit, which is acceptable for a list tool with no output schema.

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

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

Schema description coverage is 100% and the single optional 'environment' parameter is fully documented in the schema, so the baseline is 3. The description does not reference the environment parameter at all, adding no meaning beyond the schema.

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

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

The description gives a specific verb and resource — 'List Db2 subsystems (locations)' — and scopes it to 'available via Db2 REST', which distinguishes it from sibling listers like list_cics_regions or list_environments. It stops short of explicitly naming the sibling it is not.

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 is only implied: the tool is for enumerating Db2 subsystems and the parenthetical 'requires DB2_LOCATION' signals a prerequisite. There is no statement of when to choose this over search_db2_catalog or list_environments, and no exclusion 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: each listed environment carries its own read-only and role policy, which tells the agent this call doubles as a permissions probe before attempting writes.

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 dense sentence with the resource and scope front-loaded and zero filler. It is compact, though the parenthetical example list and policy clause pack in enough that it borders on compressed rather than structured.

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 carries the burden of signaling return content, and it does so by naming both the environment identifiers and the per-environment read-only/role policy. The remaining gap is the optional filter parameter's effect, which the schema covers but the description does not reinforce.

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 100% and there is only one optional parameter, which itself documents the allowed values and the omit-for-default behavior. The description contributes nothing about the environment filter and arguably reads as if it always lists all environments, leaving the filtering behavior entirely to 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?

Specific verb+resource ("List the named z/OS environments") with concrete examples (DEV/TEST/UAT/PROD, LPARs) and a stated scope ("this server can reach"). No sibling tool overlaps this discovery role, so explicit differentiation is less critical, but the description never turns that absence into an explicit positioning statement.

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 is implied rather than stated: the description tells you it enumerates reachable environments and their policies, which suggests calling it before targeting an environment, and the schema cross-references "see list_environments" in other tools' params. It never says when not to call it or what to do with the result, and does not explain the interaction with its own optional environment filter.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the fact that results can be capped, but says nothing about what happens when the cap is hit (silent truncation vs. a truncation notice), result ordering, or whether filtering is server-side versus applied client-side after retrieval.

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, zero preamble, purpose front-loaded before the cap note. Slightly thin rather than bloated; the only weak element is the unqualified "supports result capping" phrase, which could be replaced with something load-bearing.

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?

Six optional parameters at full schema coverage and no output schema means the definition is minimally sufficient to invoke. But for a listing tool it omits things an agent needs to reason about results: default cap value, result ordering, and truncation behavior, which the sibling-heavy context makes more consequential.

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 100%, so every parameter including the environment pointer and returnCode formats is already documented in the schema. The description's filter list duplicates that rather than adding semantics (e.g., how filters combine, whether status filtering is post-retrieval). Baseline 3 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 z/OS batch jobs") and enumerates the filter axes, which maps cleanly to the schema. It does not, however, distinguish itself from close siblings like find_failed_jobs or get_user_jobs_summary, which an agent would plausibly confuse it with.

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?

There is no when-to-use / when-not-to-use guidance and no named alternative, despite the sibling set containing several overlapping job-listing tools (find_failed_jobs, get_user_jobs_summary, scheduler_job_status). "Supports result capping" is a capability note, not usage 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds that result capping is applied after filtering and sorting, which is useful, but says nothing about environment targeting behavior, error cases for non-existent paths, or whether entries are recursive (they presumably are not).

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 no filler, purpose front-loaded before the capability summary. Slightly thin rather than bloated, so not a 5 on the 'every sentence earns its place' scale but close.

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, the description should say what an entry looks like (name, type, size, modified time) or that results are non-recursive. Those gaps remain, though the rich annotations and fully documented schema cover most of what an agent needs to invoke 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 100%, with enum values documented inline (sort order semantics, type filter, maxResults). The description merely restates those capabilities, so baseline 3 is appropriate; it adds no format or default details beyond the schema.

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

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

States a specific verb and resource ("List the contents of a USS directory") and names the supported refinements, so the agent knows exactly what the tool returns. It does not explicitly contrast with siblings like search_uss_files or read_uss_file, leaving that differentiation to inference.

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 phrase "Supports type filter, sort order, and result capping" is a feature list rather than guidance on when to call this versus search_uss_files or read_uss_file. Usage is implied by the name (browse a directory) but no exclusions or alternatives are given.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior, so the bar is lower. The description usefully discloses the content returned (explanations, common causes, remediation steps), which goes beyond the annotations. It does not mention result size, pagination, or ordering, so it is not fully rich.

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 primary purpose and examples, then the secondary catalog/search mode. 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?

With four optional parameters at full schema coverage and safety annotations present, the description needs only to convey returned content, which it does (explanations, causes, remediation). Lacking an output schema, it could still say more about result shape, but overall it is complete enough to call 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 100%, so all four parameters are fully documented in the schema. The description adds only a general mention of catalog search and category filtering, which mirrors what the schema already says; no extra syntax or format detail is provided beyond that baseline.

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 ("look up") and resource ("z/OS abend codes") with concrete examples (S0C7, S806, etc.), so the agent knows exactly what it retrieves. It does not differentiate from the sibling summarize_abends, which also concerns abends, so it falls short of the 5 bar.

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 phrase "Supports catalog search and category filter" implies that omitting a code lists/searches the catalog, and the schema confirms "Omit to list or search the full catalog." However, there is no explicit when-to-use guidance, no named alternative (e.g., summarize_abends for aggregate views), and no statement of when not to use this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds the useful fact that results carry RUNNING/RETRYING/STOPPED states and connection counts, but doesn't cover connectivity/permission prerequisites or failure behavior for an openWorld tool.

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

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

Two compact clauses with zero filler, and the resource/scope statement is front-loaded ahead of the listing hint.

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, the description does the right job of naming the returned status values and the connection counts, and the schema carries all parameter detail. It is nearly complete; only execution prerequisites for the openWorld MQ REST call 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?

Schema description coverage is 100% and every parameter (qmgr, channel, environment) is documented in the schema, including the 'default: all channels' behavior. The description's 'omit the channel name to list all' merely restates the channel parameter's schema text, adding no syntax or format detail.

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: returns channel status (RUNNING/RETRYING/STOPPED plus connection counts) for a queue manager over MQ REST. It is clearly distinct from the sibling mq_queue_status by resource type, though the description never names that 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 'Omit the channel name to list all' gives a concrete usage hint, but nothing states when to prefer this over mq_queue_status or other MQ-related siblings, and there are no exclusion conditions.

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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds only the transport note ('via MQ REST') and the metric semantics, but says nothing about behavior on nonexistent queue names, partial failures in a comma-separated list, or permission requirements on the queue manager.

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, front-loaded with the core capability and the unit of measurement. Nothing is redundant or padded.

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, the description usefully names the returned fields (curdepth, maxdepth, percent full). Annotations cover the safety profile and the schema covers all inputs. Only failure/edge-case behavior is missing, which is minor for a read-only status probe.

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 100%: qmgr, queues and environment are each fully documented in the schema, including the comma-separated queue syntax and the list_environments pointer. The description's comma-separated note merely repeats what the schema already states, so baseline 3 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 resource (MQ queues) and a specific payload (curdepth vs maxdepth, percent full), which tells an agent exactly what it gets back. It is implicitly differentiated from the sibling mq_channel_status (queues vs channels), but no explicit contrast is drawn.

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 is only implied: an agent can infer this is for checking queue depth/backlog. There is no explicit statement of when to use it versus mq_channel_status or the CICS/DB2 status siblings, and no prerequisites or 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds real value beyond that: it discloses the scoring approach (recency-weighted), the risk-level scale (LOW/MEDIUM/HIGH/CRITICAL), and that trends and top abend codes come back. It does not mention cost or runtime, which for a 30-day look-back scan would be useful.

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

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

Two sentences, front-loaded with the purpose, then the return contract. No filler, no repetition of parameter details already in 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?

With no output schema, the description correctly enumerates what comes back (risk levels, trends, top abend codes), and the three optional parameters are fully documented in-schema. The only real gap is routing guidance against the several failure-analysis siblings, which the description leaves unaddressed.

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 100% and each of the three parameters carries its own default and bounds documentation, so the schema does the heavy lifting. The description only indirectly touches semantics via "recurring failures," which loosely maps to minFailures but adds no new syntax or interpretation. Baseline 3 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 ("Predict batch failure risk") and scopes it to job names with recurring failures, distinguishing it implicitly from retrospective siblings like find_failed_jobs and analyze_job_failure. It also names the mechanism (recency-weighted scoring) and the outputs, so an agent knows what it produces. No sibling is named explicitly, so it stops 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?

There is no explicit statement of when to use this versus find_failed_jobs (historical failures) or analyze_job_failure (single-job deep dive), nor any prerequisites, cadence, or exclusion. The phrase "job names with recurring failures" implies a proactive-risk use case, but the agent must infer it.

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?

The annotations already establish read-only, idempotent, non-destructive, open-world behavior. The description adds source context (configured USS path or dataset) and filter coverage, but it does not disclose return format, authorization requirements, or how errors or missing audit data are handled.

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

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

The description is two compact sentences with the purpose front-loaded and no wasted wording. The filter list is secondary and supports quick scanning without overwhelming the reader.

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 an eight-parameter read-only query with full schema coverage and rich annotations, the definition is adequate to invoke the tool. Still, with no output schema it does not describe what an audit record contains, and it does not connect the environment parameter to list_environments in prose.

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 100%, so parameter semantics are already well documented in the schema. The description names most filter categories, but it adds no syntax or behavioral detail beyond the schema and omits maxResults and environment from the prose.

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 gives a specific verb and resource: query RACF security audit records, and clarifies the source is a configured USS path or dataset. It is clear what the tool does, but it does not explicitly differentiate itself from nearby security/log-analysis siblings such as security_posture_summary or analyze_logrec.

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 states that audit records can be queried and lists supported filters, which implies when the tool is useful. However, it gives no explicit when-to-use/when-not-to-use guidance and does not name alternatives for related security posture or log analysis tasks.

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?

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description contributes beyond that with the line-capped output constraint and the EBCDIC conversion caveat, which are real operational traits an agent would not otherwise know.

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 primary action and scope front-loaded and the notable behaviors (line cap, encoding) second. No filler or repetition.

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 read tool with full schema coverage and annotations, the description covers mode selection, output size, and encoding well. It is slightly incomplete in not mentioning error behavior (e.g., missing dataset or member) or how the line cap interacts with the server maximum, but these are minor.

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 100%, so dsn, member, encoding, maxLines, and environment are already documented, including the ibm1047 example and the server-configuration cap. The description restates 'custom line limits' and 'EBCDIC encoding hints' without adding format or limit semantics, so the baseline 3 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?

The description names a specific verb (read) and resource (sequential dataset or PDS member) and scopes the result ('output is line-capped'). This clearly separates it from siblings such as list_datasets, search_dataset, and get_dataset_info, which enumerate or describe rather than return content.

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 is only implied: 'Omit for a sequential dataset' tells the agent how to pick between two modes, but nothing says when to prefer this over search_dataset (to locate content) or get_dataset_info (to inspect metadata) first. The agent can infer the workflow but is not guided.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds that custom line limits and text grep filtering are supported, but does not discuss errors, truncation behavior, or output format. This is adequate but not rich given the annotations already present.

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

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

The description is two short sentences, front-loaded with the core action and followed by capability details. Every sentence carries useful information with no 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?

For a simple read-only file-reading tool with complete schema descriptions and annotations covering safety, the description is nearly sufficient. It could say more about binary files, encoding, or truncation handling, but no output schema exists and the essential behavior is conveyed.

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 100%, so all four parameters are fully documented in the input schema. The description mentions line limits and grep filtering at a high level, which maps to maxLines and searchText, but adds no syntax or behavioral detail beyond the schema. The baseline of 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?

The description uses a specific verb and resource: 'Read the contents of a USS file.' It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools like search_uss_files or list_uss_directory.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. It mentions line limits and grep filtering but does not say when to choose read_uss_file over search_uss_files, list_uss_directory, or similar 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?

The annotations already declare a non-read-only, open-world, non-idempotent write. The description adds that this is a "gated write" via a specific JES2 command, which is useful context beyond annotations. However, it does not explain what "gated" requires, what side effects releasing a job has, or what approval path may be involved.

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 a single front-loaded sentence with no wasted words. It puts the action, target, and command mechanism first.

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

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

The schema is fully described and annotations cover safety traits, so an agent has enough to invoke the tool. Still, the description leaves important mutation context unstated, especially what "gated write" means in practice and whether a separate approval step is required.

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 100%, so the schema already documents jobId, consoleName, and environment. The description adds no parameter-specific meaning beyond what is already in the structured schema, which is the baseline for full schema coverage.

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

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

The description states a specific verb and resource: release a held batch job. It also names the underlying JES2 "$OJ" command, making the operation concrete. It does not explicitly distinguish itself from siblings such as hold_job or cancel_job, 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 phrase "held batch job" implies the condition for use, but the description gives no explicit when-not guidance and does not name alternatives like hold_job, cancel_job, or approve_write. Usage is therefore implied rather than fully directed.

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