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

With no annotations, the description carries the behavioral burden. It discloses that this is heuristic, operates on the current screen, and returns non-empty stripped lines with row numbers. The word 'Return' implies a read-only inspection, though it does not explicitly state that the screen is not modified.

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 definition is compact and front-loaded. The first sentence gives the core purpose, and the second adds the heuristic caveat and intended usage without extra fluff. Every sentence earns its place.

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

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

For a zero-parameter, read-only inspection tool with an output schema, this description is complete. It states what is returned, the heuristic nature, and why the AI would call it. No critical behavioral or contextual information 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?

There are zero parameters, so there is nothing for the description to clarify. The baseline for no parameters is 4, and the description correctly adds no unnecessary parameter details.

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: 'Return a per-row inventory of non-blank content on the current screen.' This clearly distinguishes the tool from siblings like get_screen or find_text because it defines a unique result shape: per-row, non-blank, stripped 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?

It explicitly states the intended use: 'so the AI can locate input fields by neighboring labels.' It also warns 'Heuristic only', which sets expectations. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of full guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It goes beyond a basic scan by explicitly revealing a meaningful side effect: 'Trips lockout if abend found.' This is valuable non-obvious behavior for an agent to know. It does not explain what lockout entails or what happens when no error is found, but the presence of an output schema partially covers return expectations.

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 with no wasted words. The primary action is front-loaded, and the critical lockout side effect immediately follows. Every sentence contributes essential information.

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

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

For a zero-parameter tool with an output schema present, the description is largely complete: it states what is scanned, what is detected, and the important lockout side effect. Minor ambiguities such as the exact meaning of 'lockout' or which specific error markers are recognized remain, but they do not seriously hinder 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?

The tool has zero parameters, so there are no parameter semantics for the description to clarify. The empty input schema leaves nothing ambiguous, and the description does not need to add parameter-level detail. The baseline of 4 for a zero-parameter tool 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 ('Scan') and a clear resource/scope: the current screen, looking for abend codes or error markers. It also adds a distinctive side effect, 'Trips lockout if abend found,' which clarifies the tool's special role. It does not explicitly distinguish itself from sibling tools such as find_text or analyze_screen_fields, but the purpose is still unambiguous.

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

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

The description implies the tool should be used when the agent needs to detect abend codes or error markers on the current screen. However, it gives no explicit guidance about when to prefer this over siblings like find_text, get_text_at, analyze_screen_fields, or check_job, and it mentions no 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?

No annotations are provided, so the description carries full responsibility. It discloses that the tool queries current state, returns an exact set of possible states including NOT FOUND and UNKNOWN, and explains the 'last' resolution. It does not describe side effects (likely none), permissions, nor what happens on errors (e.g., if connection fails). But for a read-only status check, the state list and resolution semantics add transparency beyond the schema. It doesn't mention whether it disconnects or changes connection, but the sibling 'reconnect' and 'status' tools suggest connection state is separate.

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 compact and efficient: a one-line purpose, a helpfully formatted state list, and a terse but sufficient parameter explanation. It front-loads the core purpose and immediately gives the actionable info (states and the 'last' special value). No wasted words; every sentence earns its place.

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

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

Given one parameter, no annotations, a simple output schema (not shown but likely a state string or enum), and low schema coverage, the description provides enough for an agent to call correctly: it defines the parameter format, explains special 'last', and enumerates possible return values. However, it doesn't specify the output schema format (e.g., whether it returns a string or object) nor error handling for missing job id. But with only one param and the tool's simplicity, the gap is minor, so 4 is justified.

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

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

Schema coverage is 0%, and the schema only says 'job_id' is a string with no description. The description's argument section adds meaning: 'job_id: JES job id (e.g., JOB01234)', and clarifies the special literal 'last'. This adds meaning beyond the schema's bare property name. However, it doesn't specify format constraints beyond example, nor does it clarify if whitespace matters. Still, for a single param with clear naming, the description adequately compensates for low 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 clearly states it returns the current JES state of a job, with a specific resource (job) and an enumeration of possible states. It distinguishes from siblings like list_my_jobs (which lists jobs) because it checks one job's status, not a list. However, it doesn't explicitly differentiate from potential job-status tools, but among the siblings, none check single job status except fetch_sysout, which is for output.

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

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

The description implies usage: call when you need to know the state of a specific job, using its JES id. It defines special value 'last' for the most-recently-submitted job, which is helpful. However, it doesn't explicitly say when NOT to use it vs. alternatives like fetch_sysout (for output) or list_my_jobs (for finding IDs). The guidance is adequate but not explicit about 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?

With no annotations, the description takes on the full burden and discloses two important behavioral traits: the operation is idempotent and it does not perform login. These go beyond the bare action and shape an agent's expectations about side effects and subsequent steps. It stops short of describing failure conditions or connection state changes, but for a zero-parameter connect tool the provided transparency is solid.

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

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

Three short sentences, no filler. The core action is first, followed by essential qualifiers ('Idempotent') and the critical non-login warning plus next step. Every sentence earns its place.

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

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

For a zero-parameter connectivity tool with an output schema, the description covers the key contextual facts an agent needs: what the tool does, that it is safe to repeat, and that authentication must happen separately. It is slightly incomplete in not addressing reconnect/disconnect lifecycle, but this is a minor gap given the tool's simplicity.

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

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

The tool has zero parameters and the schema coverage is 100%, so there is no parameter meaning to add. Per the calibration baseline for no parameters, a score of 4 is appropriate; 'configured host' refers to static configuration, not a parameter.

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 concrete verb-resource pair: 'Open a TN3270 connection to the configured host', and immediately distinguishes itself from login by stating 'Does NOT log in'. This clearly separates connect from its siblings and makes its function unambiguous.

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

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

The description explicitly instructs the agent to call `login(userid)` afterwards, establishing that connect is only the first step and not a substitute for authentication. It also signals through 'Idempotent' that repeated invocations are safe. It does not, however, contrast with closer siblings like reconnect, leaving some usage selection up 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?

No annotations are provided, so the description carries the full burden. It adds 'cleanly' as a behavioral qualifier, but does not disclose prerequisites (active session), side effects (what happens to pending data), or error behavior if no session exists. This is a minimal disclosure for a session-terminating operation.

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

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

A single front-loaded sentence with no filler. It is appropriately sized for a zero-parameter action, and every word contributes to the meaning.

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

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

For a zero-parameter action with an output schema, the description is mostly adequate, but it omits preconditions and does not contrast with force_cleanup or reconnect. It is not fully complete, though the low complexity keeps the gap from being severe.

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

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

The tool has zero parameters and the description correctly adds no parameter information. The baseline for a zero-parameter tool is 4.

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

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

The description uses a specific verb ('Close') and resource ('TN3270 session'), and 'cleanly' implies a graceful teardown that contrasts with the sibling force_cleanup. It is immediately clear what the tool does and how it differs from connect/reconnect/force_cleanup.

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 only guidance is 'Close the TN3270 session cleanly,' which implies using it when the agent wants to end a session. It does not explicitly say when to prefer it over force_cleanup or whether it requires an active connection, so the usage context is left to inference.

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

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

With no annotations provided, the description carries the full burden. It discloses that the spool is purged after fetch, which is a critical side effect, and that abend detection triggers a lockout similar to check_for_errors. It also clarifies the ddname parameter's current informational nature. This is solid but does not cover every edge case like error handling for nonexistent jobs.

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

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

The description is concise, around 120 words, with the core purpose front-loaded. It uses a clear structure: a one-sentence summary, then behavioral details, then an args list. Every sentence adds value with no filler.

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

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

The tool has a simple signature with one required param and an output schema (indicated but not shown). The description covers the main purpose, side effects, and parameters, which is sufficient for most use cases. However, it does not mention potential error conditions or prerequisites like requiring an active session, though these might be implied by the tool family. Minor gap.

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

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

Schema coverage is 0%, so the description must explain parameters, and it does excellently. job_id is explained with the 'last' special value, and ddname is given context about its future use and current limitations. This fully compensates for the lack of schema descriptions.

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

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

The description clearly states the verb 'fetch' and resource 'SYSOUT', and adds the key outcome of surfacing RC and abend. It also mentions side effects (purge) which help differentiate from other tools like check_job. The purpose is unambiguous and specific.

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

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

The description implies usage by mentioning detection of abends similar to check_for_errors, but it does not explicitly state when to prefer this tool over alternatives like check_job or list_my_jobs. There is no clear exclusionary guidance or conditional use case. The 'currently informational only' for ddname is a useful hint but not a full usage rule.

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 description discloses meaningful behavioral details: searching is literal and case-sensitive, and it is scoped to the current screen. However, with no annotations, it remains silent on no-match behavior and whether any refresh or waiting occurs.

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 short, front-loaded, and free of fluff. The first sentence states the purpose, and the second documents the argument without repeating schema 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 one-parameter tool, it covers the required argument and the output shape. Its main gaps are the lack of sibling-routing guidance and missing edge-case behavior such as what happens when the pattern is not found.

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

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

The schema only defines pattern as a string, so the description's 'Exact text to search for. Case-sensitive.' adds real semantic value. This compensates for the 0% schema description coverage and makes the single parameter unambiguous.

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 clear operation: 'Return all (row, col) coordinates where the literal pattern appears on the current screen.' The mention of coordinates and literal pattern gives it a distinct identity among siblings, though it does not explicitly name 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 only usage cue is 'current screen,' which implies a direct, non-waiting screen search. There is no guidance on when to prefer this over siblings like wait_for_text or get_text_at, and no exclusions or alternative conditions 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It details the two-step process (robust logoff, then operator instruction) and states the output ('Returns a single-line status'). It does not explicitly warn about side effects or risks, but the destructive nature is implied and the steps are transparent enough.

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

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

The description is front-loaded with the purpose, uses a clear numbered step structure, and each sentence contributes meaning (purpose, condition, steps, output). It is concise without being terse, and every sentence earns its place.

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

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

Given the zero-parameter tool, an output schema (if present) would handle return details, and the description already mentions the return format. It covers when to use, the process, and expected output. Combined with the sibling context, an agent has all information needed to select and invoke the tool correctly. No gaps are evident.

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

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

The tool has zero parameters, so the schema coverage is 100% trivially. Baseline for 0 params is 4. The description references a 'configured userid' but that is a config context, not a parameter, so no parameter-specific semantics are needed. The description adds no import because there are no parameters to explain.

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 opening line 'Force-reset the host-side session for the configured userid' names a specific verb (force-reset) and resource (host-side session) and ties it to a specific scenario ('holding the userid as IN USE'), clearly distinguishing it from siblings like reconnect or disconnect.

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

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

The description explicitly states when to use: 'Use when a prior dirty disconnect (or external session) is holding the userid as "IN USE" and blocking new logons.' This is a precise trigger condition, though it does not explicitly mention alternatives or when not to use; the condition is specific enough to route correctly.

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

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

With no annotations, the description carries the behavioral burden. 'Return' indicates a read-only operation and the exact output fields are listed, which is transparent. However, it does not disclose prerequisites, error behavior, or whether an active connection is required, leaving some behavioral gaps.

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

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

The description is minimal and front-loaded: one sentence states the purpose and exact output, followed by a single-line parameter explanation. Every element earns its place with no redundant wording.

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 tool with one required parameter, no nested objects, and an output schema present, the description covers purpose and parameter adequately. The main missing element is usage guidance, but the simple read-only nature of the tool makes the description mostly complete.

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

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

The schema only defines 'dataset' as a string with no description, while the description's Args section adds meaningful semantics: 'Fully-qualified dataset name'. This compensates for the 0% schema coverage, though it could include an example or naming convention for full clarity.

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 ('Return') and resource ('DCB attributes') for a single dataset, enumerating exact attributes (RECFM, LRECL, BLKSIZE, DSORG, volume). This clearly distinguishes it from sibling tools like list_datasets or read_member, which operate on dataset lists or member 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?

No explicit guidance is given about when to use this tool versus siblings such as list_datasets or read_member. The purpose is implied by the description, but there are no usage conditions, exclusions, or alternative-selection heuristics.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It transparently states that this is a read operation returning the current screen and discloses the row-numbered 24x80 format. However, it does not mention whether the call waits for screen stability, how connection failures are handled, or whether the snapshot is immediate.

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 action, object, and output format efficiently, earning its place entirely.

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, has no parameters, and has an output schema, so the return shape is covered. However, given the large sibling set of screen-related tools, the absence of any guidance on when to choose get_screen over alternatives leaves the description slightly incomplete for correct tool selection.

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

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

The tool has zero parameters and the schema covers 100% of them (empty properties). The baseline for no parameters is 4; the description adds no parameter details because none are needed. Nothing is left undocumented.

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

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

The description uses a specific verb ('Return'), names the resource ('current 3270 screen'), and specifies the format ('row-numbered, 24 rows x 80 cols'). This clearly distinguishes it from sibling screen tools like find_text or get_text_at, which operate on content rather than returning the full screen.

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

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

No guidance is given on when to use this tool versus alternatives such as wait_for_screen_change, identify_screen, or get_text_at. The description implies it is for retrieving the full current screen, but it does not state exclusions or recommend sibling tools for other screen-related 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?

No annotations are provided, so the description carries the full burden. 'Return' implies a read-only operation, and the coordinate ranges (1-24, 1-80) give some screen size context. However, it doesn't disclose what happens on out-of-range inputs, whether it returns an empty string for blank areas, or explicitly state that it has no side effects.

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

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

The description is compact and well-structured: a single clear purpose sentence followed by a bullet-like Args block. Each parameter line adds specific meaning without redundancy or fluff, and the key purpose is front-loaded.

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

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

Given the tool has an output schema, return type details are covered elsewhere. The description supplies enough for correct invocation: coordinate ranges, character count, and the default of 80. It doesn't address when to choose this over siblings, but that gap is more about usage guidelines than operational completeness.

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

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

With schema description coverage at 0%, the description provides essential semantics: row and col are 1-based with valid ranges, and length is the number of characters to read. This fully compensates for the barren schema. The default length of 80 is only in the schema, but the description still clarifies each parameter's purpose.

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

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

The opening sentence 'Return text at a specific screen position' clearly states a specific verb and resource, making the core function obvious. It differentiates from siblings like get_screen or find_text by emphasizing location-based reading, though it doesn't explicitly name an 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 description gives no indication of when to use this tool versus alternatives such as get_screen, find_text, or analyze_screen_fields. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer appropriate usage from the tool name 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?

With no annotations, the description carries the behavioral burden. It discloses that the tool matches against known signatures and returns screen_id values including UNKNOWN, which clarifies the non-mutating classification behavior. It does not explicitly state that it performs no writes or describe error/prerequisite behavior, but the verb and return values imply read-only 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: one purpose statement and one output-format line with helpful examples. 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 zero-parameter tool with an output schema, the description is nearly complete: it gives the action, the mechanism, and example outputs. A small gap is that it does not mention whether an active connection is required or that no screen mutation occurs, but the simple tool shape makes this 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?

The tool has zero parameters in the input schema, so there is nothing to document. The description's list of example screen_id values adds semantic context even though no parameters exist.

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

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

States a specific verb (identify), a resource (current screen), and a concrete output (screen_id from known signatures, with example values). This distinguishes it from sibling tools like get_screen, which would return raw screen content rather than a classification.

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 the use case: call this when you need to know which screen you are on. However, it does not explicitly state when to prefer it over siblings such as get_screen or analyze_screen_fields, nor does it provide exclusion criteria.

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

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

No annotations are provided, so the description bears the full burden. It discloses the underlying transport (ISPF vs FTP) and the login requirement for ISPF, which are meaningful behavioral details. It does not discuss rate limits or error handling, but for a read-only list operation, this level of transparency is sufficient. The output schema likely covers return values, so no need to duplicate.

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 compact and well-organized: a one-sentence purpose, a brief usage note about transport and login, and a clear Args definition. Every sentence earns its place, with the most critical information (matching pattern) front-loaded. No filler or redundancy.

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

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

For a single-parameter list operation with an output schema, the description covers the essential aspects: what it lists, how to specify the pattern, and the operational prerequisites. It doesn't mention potential limitations (e.g., case sensitivity, session state for FTP), but these are minor and the core usage is fully explained.

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

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

The schema itself has zero description coverage for the single 'pattern' parameter, but the description's Args section fully compensates: 'Fully-qualified dataset name with wildcards (``*`` matches any qualifier)'. This adds precise semantics that the schema lacks, including wildcard syntax and qualification format, making it easy for an agent to construct valid inputs.

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

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

The description clearly states the action: 'List MVS datasets whose name matches pattern' – a specific verb and resource. It also distinguishes from siblings like list_members (which lists members within a dataset) and get_dataset_info (which fetches info on a single dataset), leaving no ambiguity.

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

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

The description explains the transport mechanism (ISPF 3.4 or z/OS FTP) and the prerequisite that the TN3270 session must be logged in when using ISPF. This gives clear context on when the tool is usable. It doesn't explicitly mention alternatives or when not to use it, but the prerequisites and transport choice serve as adequate guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the input format constraint (no trailing (*)) but doesn't mention what the output looks like, whether it requires a connection, or any side effects. For a read-only listing tool, this is a moderate 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?

The description is extremely concise, with a clear example and a single important constraint. Every sentence earns its place, and the key usage note is front-loaded.

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

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

For a simple one-parameter tool with an output schema, the description is mostly adequate. It covers the essential input format. However, it doesn't mention whether a connection must be active, what happens with invalid PDS names, or how the output is structured, which an agent might need to know for error handling.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the pds parameter meaning and format, which adds value beyond the bare schema. However, it doesn't provide examples of valid values beyond the one example or clarify edge cases like quoted vs unquoted names.

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

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

The description clearly states the tool lists members of a PDS and gives a concrete example. It is distinct from siblings like list_datasets and read_member, though it doesn't explicitly differentiate itself.

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

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

The description implies usage by specifying the input format (PDS name without trailing (*)), but it doesn't state when to use this tool versus alternatives like list_datasets or read_member. The context is clear enough for a simple tool, but no explicit exclusions or alternatives are given.

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

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

With no annotations provided, the description carries the behavioral transparency burden. The verb 'List' clearly signals a read-only, non-mutating operation, and the parenthetical TSO STATUS comparison adds precise behavioral context about what is returned. It could go further by noting there are no side effects or prerequisites, but for a zero-parameter read tool this is largely sufficient.

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, tightly worded sentence with no filler. It front-loads the core purpose and adds the TSO comparison as a useful parenthetical without bloating the text.

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

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

For a zero-parameter list operation with an output schema present, the description is complete. It tells the agent what is listed, whose jobs are included, and the mainframe command it corresponds to, which is enough to select and invoke the tool correctly.

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

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

There are zero parameters, so the baseline is 4; there is nothing the description needs to add beyond the empty schema. The description also indirectly clarifies why no jobid is needed by referencing TSO STATUS with no jobid.

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 ('List') and a clear resource ('jobs owned by the current userid'), and the TSO STATUS comparison clarifies exactly what the tool does. This distinguishes it from sibling tools like check_job (a single job) and list_datasets/list_members (different resource types).

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 establishes clear scope: it lists only the current user's jobs, equivalent to TSO STATUS with no jobid. However, it does not explicitly name alternative tools or state when to prefer this over check_job or fetch_sysout; usage timing is implied rather than directly 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?

With no annotations provided, the description must disclose behavior on its own. It usefully explains that the password is fetched from the OS keychain and must be set once beforehand, which is valuable context. However, it does not describe side effects such as session creation, failure behavior, or whether an existing connection is required.

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 short and front-loaded: the first sentence states the action, the second explains authentication behavior, and the third gives the prerequisite. Every sentence contributes value with 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 single-parameter login tool, the description covers purpose, authentication source, and setup, and an output schema exists. However, it omits whether a prior connection is required, how it interacts with the sibling connect/disconnect tools, and what happens on login failure. These gaps matter in an environment with connection-management siblings.

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

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

The schema has 0% description coverage, so the description must compensate. It does add meaning by defining userid as a RACF userid, but it provides no additional format, validation, or usage details beyond that single label. This is minimal but non-redundant.

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

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

The description clearly states the action ('Log in to TSO') and the target resource (TSO) with the userid parameter. It does not explicitly distinguish itself from the sibling tool 'connect', which could be a related but different operation, 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 description gives a clear prerequisite ('Set the password once via scripts/set_password.py before calling this') and implies when to use the tool, but it does not discuss when not to use it or how it compares with siblings like connect, reconnect, or status. This is adequate but not explicit.

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

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

With no annotations provided, the description carries the disclosure burden. It communicates that the operation is a read and returns text, but does not mention behavior on missing members, encoding, or any preconditions like an active connection. 'Read' implies no mutation, though the description does not explicitly confirm side-effect-free 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 two purposeful lines with no filler. The core behavior is front-loaded, and the Args section directly supports the only parameter.

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

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

For a one-parameter read operation, the description covers the essential input format and purpose, and an output schema exists so return-value details need not be repeated. It does not mention prerequisites such as an established connection or what happens when the member does not exist, but these are minor for such a simple tool.

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

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

Schema description coverage is 0%, so the description must supply parameter meaning. It does so by specifying the expected PDS.NAME(MEMBER) form for pds_member, which is essential and not present in the schema. It stops short of giving examples or formatting details, but the single-parameter case is well addressed.

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 ('Read') and resource ('PDS member') and clarifies the output format ('as text'), making the tool's purpose unambiguous. This also differentiates it from sibling tools like list_members and list_datasets, which operate on collections rather than a single member's contents.

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 statement implies when to use the tool: when the contents of one PDS member are needed as text. However, it does not explicitly state when not to use it or name alternatives such as list_members for discovering members, leaving usage context 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the force disconnect and re-login behavior, but does not disclose potential side effects (e.g., interrupting ongoing operations, requiring authentication, failure modes, or what happens if no userid was set). This is a significant gap for a session-management tool that could affect system state.

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 concise sentence that immediately conveys the core action and a key conditional behavior. It is front-loaded and contains no extraneous information. Efficient and well-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?

While the output schema exists (which covers return values), the description lacks important contextual details such as prerequisites, side effects, and typical use cases. Given the sibling set includes connect, login, and disconnect, the tool's role as a combined reset is implied but not fully explained. The description is adequate for a trivial tool but misses opportunities to clarify when to use it.

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

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

The tool has zero parameters, and the schema is empty. The baseline for 0 params is 4, as no parameter explanation is needed. The description adds behavioral context beyond the schema, which is appropriate. There is no parameter-related ambiguity.

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

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

The description clearly states the tool's action: 'Force a disconnect + reconnect.' It also adds a specific behavior about re-logging in if a userid was previously set. This distinguishes it from plain connect or disconnect siblings, though it doesn't explicitly name them. It is specific enough for an agent to understand the primary function.

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

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

The description provides no guidance on when to use this tool versus alternatives like calling disconnect followed by connect. It does not mention prerequisites, scenarios where this is preferred, or when it should be avoided. The 'Force' hint implies a reset, but the lack of explicit usage context leaves the agent to infer.

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

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

With no annotations provided, the description carries the full behavioral burden. It states the action and that the tool returns the resulting screen, which is useful, but it does not explain what the CLEAR AID key does (e.g., cleans the current screen) or any side effects, timeouts, or error behavior. This is minimum viable transparency for a zero-parameter key-send tool.

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

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

The description is a single front-loaded sentence with no filler. The action verb comes first and the return behavior second; every word carries meaning.

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

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

For a zero-argument tool with an output schema present, the description conveys the essential purpose and return behavior. It could be slightly more complete by explaining when CLEAR is useful versus other AID keys, but nothing needed to invoke the tool correctly is missing.

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

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

The input schema has zero parameters stub, and description coverage is 100%, so there is no parameter information missing from either source. With no parameters to document, the baseline of 4 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 names a specific verb ('Send') and resource ('the CLEAR AID key'), and adds the return behavior ('Returns the resulting screen'). This is clearer than the tool name alone, though it does not explicitly contrast with sibling key-sending tools like send_keys, send_pf, or send_pa.

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 guidance on when to choose send_clear over sibling key-sending tools, nor any mention of prerequisites or when not to use it. The only implied context is 'when you need to press CLEAR,' which is not enough to differentiate usage.

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

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

With no annotations, the description carries the full burden and does a good job: it states the primary action and the outcome ('Returns the resulting screen'). This goes beyond the name by confirming the tool both sends the key and waits for/returns the updated screen state.

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 containing exactly two pieces of information: what is sent and what is returned. There is no filler, repetition, or ambiguity.

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 parameterless action with an output schema, the description covers the essential call semantics — the specific key and the response. It doesn't mention preconditions like an active connection, but that is plausibly handled by the broader tool set and the simplicity of the 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?

The input schema is empty, and the parameter count is 0, so there are no parameters to describe. The baseline for 0 params is 4, and the description adds no unnecessary parameter 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?

Identifies the exact action (send the ENTER AID key) and specifies the resource (the ENTER AID key), clearly differentiating it from siblings like send_pf, send_pa, and send_clear. Also states the resulting action returns the screen, which adds operational clarity.

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

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

No guidance on when to use this tool instead of alternatives such as send_pf or send_keys. The context of the tool is implied by the name, but the description does not provide explicit when-to-use 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?

With no annotations, the description carries the full burden and it discloses key non-obvious behaviors: it does not submit, and it should not be used for passwords. This goes beyond the schema. However, it omits edge cases like what happens if no input field is focused, so it is not fully exhaustive but still strong.

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 compact: three sentences covering purpose, non-submit behavior, and usage guidance, plus a one-line args description. Every sentence adds essential information, and the key behavioral points are front-loaded.

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

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

The tool has an output schema, so return values are covered elsewhere. The description fully explains the tool's action and its place in the workflow (followed by send_enter/send_pf). It could mention error conditions or behavior without a focused field, but for a simple single-parameter typing tool, this is nearly 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 0%, so the description must compensate. The 'text' parameter is described only as 'Characters to type,' which is minimal but does convey its purpose. It lacks details about formatting, encoding, or special keys, but given the parameter's simplicity, this is adequate yet not rich.

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

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

The description explicitly states 'Type text into the current input field at the cursor position' with a specific verb and resource, and immediately clarifies 'Does NOT submit.' This clearly distinguishes it from sibling tools like send_enter and send_pf, leaving no ambiguity about its function.

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

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

It provides direct instructions: 'Use send_enter / send_pf afterwards to submit' and explicitly warns 'Do NOT use for passwords; the login tool fetches them from the OS keychain.' This gives clear when-to-use and when-not-to-use guidance with specific 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?

No annotations are provided, so the description carries the behavioral burden. It usefully discloses that the tool 'Returns the resulting screen' and that the key number is 1-3. It does not mention attention-key semantics or potential side effects, but for a simple one-parameter send action this is minimally adequate.

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

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

The description is compact and front-loaded: the action and parameter range appear immediately, and the Args section is clear. Every sentence contributes meaning, with 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 simple tool with one parameter and an output schema, the description covers the core details: what is sent, the allowed range, and the return value. However, given the sibling context with send_pf, send_enter, and send_keys, an agent still lacks enough guidance to confidently choose send_pa over the alternatives.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it defines 'number' as 'PA key number (1-3),' adding a valid range and domain meaning beyond the bare integer schema. This is sufficient for an agent to invoke the tool correctly.

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 clear verb and resource: 'Send a PA key (1-3).' This is specific and intelligible. It does not explicitly differentiate from sibling tools like send_pf, send_enter, or send_keys, though the term 'PA key' provides some inherent distinction.

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

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

There is no guidance about when to use send_pa versus the many related send_* tools. The description implies usage only by naming the action, but it does not explain when a PA key is appropriate, when not to use it, or how it differs from PF/Enter/Clear keys.

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

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

No annotations are present, so the description carries full responsibility for behavioral disclosure. It only states that it sends a PF key and returns the resulting screen. It omits details about synchronization, error handling, connection prerequisites, or side effects beyond the screen change.

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

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

The description is very short and front-loaded with the core action and return value, which is efficient. However, it is under-specified rather than concise in a helpful way, lacking any additional context that would justify its brevity.

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

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

Given the tool's simplicity and the existence of an output schema, the description covers the basic function but misses important context such as when to use it (e.g., for mainframe navigation), whether a connection must be active, and how it differs from related tools. It is adequate for a trivial tool but not fully complete.

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

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

The schema provides a required integer 'number' with no description (0% schema coverage). The tool description adds the range '1-24' and clarifies it is a PF key number, which is some added meaning, but it does not explain the semantics of PF keys, valid ranges, or out-of-range behavior. The compensation is minimal.

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

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

The description clearly states the verb 'Send' and the resource 'PF key' with a numeric range (1-24), and notes the return value is the resulting screen. It is specific enough to distinguish from siblings like send_enter or send_pa by the tool name and the PF key focus, though it does not explicitly contrast them.

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

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

There is no guidance on when to use this tool versus alternatives such as send_keys or send_pa. The intended usage is only implied by the tool name and description; no exclusions or contextual cues are provided.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does imply a read-only operation by saying 'Return a one-line status', which suggests no side effects. However, it doesn't explicitly state that it's safe, nor does it disclose any potential errors or network dependencies. For a simple status check, this is adequate but not 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?

The description is a single sentence, concise and front-loaded with the action and key fields. It wastes no words and is appropriately sized for a simple status tool. Every word adds value.

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

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

Given the tool's simplicity, the description is complete. It lists the returned fields, and since an output schema exists, the description doesn't need to elaborate on return formats. It could optionally clarify what 'mode' refers to, but that's likely covered in the schema. Overall, an agent has enough to call it correctly.

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

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

The tool has zero parameters, so the schema coverage is effectively 100%. The description doesn't need to explain parameters. It does add context about the output fields, but that's not parameter semantics. Baseline is 4 for zero-parameter tools, and the description is sufficient.

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

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

The description clearly states the tool returns a one-line status with specific fields (host, connected flag, userid, mode). It uses a specific verb ('Return') and resource ('status'), making the purpose unambiguous. It doesn't explicitly name a sibling tool, but among the siblings (connect, disconnect, get_screen, etc.), none duplicate this exact function, so it's adequately distinguishable.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, typical scenarios, or exclusions. For example, it doesn't indicate whether this should be used before or after connection, or how it relates to 'connect' or 'login'. This is a clear gap.

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

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

With no annotations provided, the description carries the behavioral burden. It usefully discloses that the tool blocks and that a timeout can end the wait, but it does not clarify what happens on timeout, whether the 'last observed state' persists across calls, or what is returned after the screen changes.

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 extremely compact and front-loaded with the core behavior. The Args section is minimal but sufficient for the single parameter, and every sentence contributes useful information.

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

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

For a single-parameter tool with an output schema, the description covers the main entry point: what it waits for and how long. However, it leaves ambiguity around the meaning of 'last observed state,' which is essential context for an agent to know when the tool can be called and what it compares against.

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

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

The schema only provides the parameter name, type, and default, while the description adds the semantic meaning 'Seconds to wait.' This compensates for the 0% schema description coverage by clearly defining the unit and purpose of the timeout parameter.

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

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

The description clearly identifies a specific operation: blocking execution until the screen changes from its last observed state or a timeout elapses. It is distinct enough from siblings like wait_for_text, though it does not explicitly differentiate itself from any named 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?

There is no guidance about when to use this tool versus alternatives like wait_for_text, get_screen, or check_for_errors. The description explains what the tool does but not the situations that call for it or when it should be avoided.

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

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

With no annotations, the description carries the behavioral burden. It discloses blocking until match-or-timeout, case-insensitive matching, and screen-wide scope, but it does not state timeout semantics (e.g., success/failure/exception), leaving a 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?

Extremely concise: the core behavior is front-loaded, followed by a two-item arg list. Every line adds useful information without 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 simple two-parameter wait tool, the essential call contract is covered and the output schema likely handles return values. However, missing guidance on alternatives and timeout/error behavior, combined with no annotation coverage, leaves some autonomy gaps.

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

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

Adds meaningful semantics beyond the raw schema: pattern is 'literal text' and case-insensitive, timeout is 'seconds to wait' with a default. With 0% schema coverage, this compensation is valuable, though no timeout range or validation rules are given.

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 blocking-wait operation on a literal pattern anywhere on screen with a timeout. The 'block until' phrasing and 'anywhere on screen' scope distinguish it from search-style siblings like find_text, but it never names 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?

No explicit when-to-use, prerequisites, or alternative routing is provided. An agent must infer that this is for waiting rather than immediate lookup; siblings like find_text and wait_for_screen_change are never referenced.

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