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

Annotations are absent, so the description carries the full burden. It does state the return value ('JSON string confirming creation of the note'), which adds some transparency. However, it does not disclose potential side effects, required permissions, or whether the operation modifies existing notes, leaving moderate 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 exceptionally concise: one purpose sentence, a clean Args list, and a returns note. It is front-loaded and every element 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 simple two-parameter tool with an output schema, the description provides the essential purpose and return type. It does not dive into edge cases or error conditions, but given the low complexity, it 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?

The schema has zero descriptions, but the description's Args section clarifies that offense_id is 'The ID of the offense' and note_text is 'The content of the note.' This adds minimal meaning beyond the parameter names themselves; there is no discussion of formatting, constraints, or behavior specifics.

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

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

The description clearly states the specific action ('Add an analyst note or investigation comments') and the target resource ('an offense'). This distinguishes it from sibling tools like qradar_update_offense or qradar_get_offense without needing to examine their schemas.

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

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

No guidance is provided on when to use this tool versus alternatives, or any preconditions such as requiring the offense to exist. The description simply explains what it does; it does not help an agent decide between this and a sibling tool like qradar_update_offense.

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 adds useful context: the operation mutates a Reference Set, writes an audit trail using the source label, and returns a JSON string confirming the addition. However, it does not disclose duplicate/overwrite behavior, permission requirements, or other side effects for this mutating 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?

The description is a compact docstring with a front-loaded purpose sentence followed by an args list and return type. Every part earns its place, with no fluff 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?

The description explains what the tool does, all parameters, and the return value, making invocation possible. Still, for a mutating tool with no annotations, it lacks important operational context such as duplicate handling, whether the set must pre-exist, and any required permissions or side effects.

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%, but the description documents all three parameters: name as the target set, value with the element_type constraint, and source as an audit label with its default. This adds meaning beyond the schema, though concrete value format examples would be stronger.

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 action—adding an IoC or indicator (IP, domain, hash, URL) into a Reference Set. This clearly distinguishes the tool from siblings like qradar_delete_from_reference_set, qradar_get_reference_set, and qradar_list_reference_sets.

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 action and argument list: use this when adding an indicator to a Reference Set. However, it does not explicitly state when to prefer this over related tools, mention prerequisites like the set needing to exist, or provide 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 behavioral burden. It clearly indicates that this is a destructive removal operation and mentions the JSON confirmation return. However, it does not disclose permanence, failure behavior, required permissions, or what happens when the value is absent.

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, uses a clear Args/Returns structure, and front-loads the action. Every sentence contributes useful information with 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 simple two-parameter delete operation, the description covers the action, both parameters, and the return behavior. It does not explain edge cases like nonexistent sets or invalid values, but the operation is straightforward and an output schema is present.

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

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

Schema description coverage is 0%, but the description compensates for both parameters by specifying 'name' as the Reference Set identifier and 'value' as the value to remove. While not deeply detailed, it adds meaning beyond the bare property titles in the schema.

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

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

The description states a specific action ('Remove a specific value') and a clear resource ('Reference Set'), which matches the tool name and distinguishes it from add/get/list siblings semantically. However, it does not explicitly contrast itself with sibling tools like qradar_add_to_reference_set.

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 when to use qradar_add_to_reference_set or qradar_get_reference_set. The description simply states the operation without providing usage context 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 provided, the description carries the behavioral disclosure burden and does it well: it states that wait_for_completion polls until COMPLETED or timeout, that false returns a search_id, and that max_results limits returned records. This gives the agent a clear model of the execution lifecycle beyond the bare schema.

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

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

The description is well-structured with an Args section and Returns section, front-loading the core purpose first. Each parameter is explained in one clear sentence, and the example query adds concrete value 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?

Given four parameters and no annotations, the description covers the essential behavior, parameters, and return format. It is slightly incomplete in not relating this tool to the search-status/results workflow, but nothing needed to invoke it successfully is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does fully. It explains query with an example AQL expression, defines wait_for_completion behavior, describes timeout_seconds with its default source, and clarifies max_results semantics including the default value.

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

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

The description opens with a specific verb and resource: 'Execute an AQL (Ariel Query Language) search on QRadar logs or flows.' This clearly identifies the action and object, and it distinguishes the tool from sibling search-status and search-results tools by framing it as the execution step.

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 execution behavior and the wait-for-completion option, which implies when an agent might use the tool. However, it does not explicitly say when to use this tool instead of qradar_get_search_status or qradar_get_search_results, nor does it give explicit when-to-use or 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It states this is a retrieval operation and discloses the return format (JSON string) and major content areas (interfaces, IPs, MACs, OS products, users, vulnerability count). It does not cover error cases or rate limits, but for a read-only get-by-ID tool this is solid 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?

The description is compact and front-loaded, with a clear purpose sentence followed by concise Args and Returns sections. Every line contributes useful information and there is 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 only one parameter, an output schema exists, and the description covers both the operation and the parameter semantics. It could add guidance on obtaining the asset ID via qradar_list_assets or behavior for nonexistent IDs, but those are not essential 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 description coverage is 0%, so the description must compensate. It defines asset_id as 'Unique integer ID of the asset,' adding semantic meaning beyond the schema's type and title. It lacks examples or range details, but with a single simple parameter this is adequate.

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 ('Retrieve') and a specific resource ('full details of a single asset'), and clearly identifies the lookup key as 'Asset ID.' Saying 'single asset' differentiates it from sibling qradar_list_assets, so an agent can understand this is a get-by-ID operation.

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 'by its Asset ID' makes clear that this tool is appropriate when the agent already has the asset ID and needs full details for one asset. It does not explicitly mention that qradar_list_assets should be used when the ID is unknown, but the context is clear enough for correct use.

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?

There are no annotations, so the description carries the burden. It discloses a read-oriented retrieval action ('Get') and clearly states the output behavior: 'Returns: JSON string containing log source properties (type, target collector, protocol, enabled status).' It does not cover error handling or auth, but for a simple by-ID getter this is 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 well structured: a one-sentence purpose, an Args line, and a Returns line. Every sentence adds useful information, and the key detail ('by ID') 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 a single required integer parameter and an output schema, the description covers the resource, the argument, and the return payload sufficiently. It could additionally point to qradar_list_log_sources for finding IDs or mention failure behavior, but those are minor gaps rather than blockers.

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

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

Schema description coverage is 0%, and the description compensates with an Args section explaining log_source_id as 'The ID of the log source.' Since this is the only required parameter and its purpose is fairly self-evident, the description provides enough added semantic meaning beyond the bare integer 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: 'Get full configuration details of a specific log source by ID.' It clearly distinguishes the tool from list-oriented siblings like qradar_list_log_sources by emphasizing that it targets one log source by its ID.

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 'by ID' gives a clear context: use this tool when the caller already has a log_source_id and needs that source's full configuration. It does not explicitly name qradar_list_log_sources as the alternative for listing or discovering IDs, so it falls just short of the strongest 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the return type ('JSON string') but does not disclose whether this is a read-only operation, whether it requires special permissions, what happens if the offense_id does not exist, or any rate-limit or pagination behavior. For a retrieval tool, the lack of error-handling or permission context is a notable 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 short and front-loaded with the main purpose. The Args/Returns structure is clear and wastes no words. It loses one point because the Returns line is slightly redundant with the first sentence ('detailed information' vs 'JSON string containing the offense details'), but overall it is efficient.

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 (one parameter, no nested objects) and the presence of an output schema, the description is mostly complete. However, with no annotations and no mention of error cases or read-only safety, an agent lacks some context that would be useful for a QRadar API tool. It is adequate for a straightforward get-by-ID operation but not rich.

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 only parameter ('offense_id: The ID of the offense to retrieve'), which adds meaning beyond the schema's bare type/title. However, it does not specify the ID format (e.g., integer range, where to find it) or any constraints beyond being an integer. With only one parameter, the description is adequate but 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 states a specific verb ('Retrieve') and resource ('detailed information about a specific offense by its ID'), which clearly distinguishes it from sibling tools like qradar_list_offenses (which lists offenses) and qradar_update_offense (which modifies). It could be slightly stronger by explicitly naming the sibling it contrasts with, but the purpose is 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 usage: use this when you need details for a specific offense ID, as opposed to qradar_list_offenses for a collection. However, it does not explicitly state when not to use it or mention alternatives. The context is clear enough for an agent to infer the right scenario, but there is no explicit 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?

With no annotations, the description carries the full behavioral burden. It discloses that the operation retrieves data and returns a JSON string, implying a safe read operation, but it does not mention error behavior for a missing map, permission requirements, or pagination edge cases. Some behavioral context is present, but the disclosure is incomplete.

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 one-sentence purpose, three parameter bullet points, and a returns line. Every sentence earns its place, and the key action 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 getter with three parameters and an output schema, the description covers the essential invocation details completely. It could be more complete by noting how to discover Reference Map names or what happens when the map does not exist, but these are minor for a tool of this complexity.

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 fully for the parameter docs. It does: 'name' is specified as the exact map name, 'limit' as the maximum entries with default, and 'offset' as the starting pagination index. This adds real semantic meaning beyond the bare schema types.

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

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

The description opens with a specific verb and resource: 'Retrieve key-value entries of a specific Reference Map.' This clearly distinguishes it from nearby sibling tools like qradar_list_reference_maps by scoping to a single map, and from qradar_get_reference_set by naming the different resource type.

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—when you need key-value entries from one Reference Map—but it does not explicitly say when to prefer this tool over siblings such as qradar_get_reference_set or qradar_list_reference_maps, nor does it mention when not to use it. There is no misleading guidance, but the context is not 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?

There are no annotations, so the description is the sole behavioral source. It clearly states this is a read operation returning JSON details and element data, and it explains pagination via limit/offset. It does not mention error handling or permission requirements, but for a simple fetch operation this is adequate minimal coverage.

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

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

The description is compact and well-organized with Args and Returns sections. Every sentence earns its place, and the key action is front-loaded. No fluff or irrelevant detail.

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 presence of an output schema, the description does not need to detail the return shape. It covers required and optional parameters, defaults, and the high-level return type. Lacking is guidance on edge cases (e.g., empty set, missing set) and any special API constraints, but those are not critical enough for a simple read.

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 is the only source of parameter meaning. It fully explains each parameter: name is the exact reference-set name, limit is the max element count with default 100, offset is the pagination starting index with default 0. This completely compensates for the bare 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 ('Retrieve') and a distinct resource ('metadata and entries of a specified Reference Set'). It clearly differentiates from the sibling qradar_list_reference_sets, which logically lists all sets, while this one fetches a single, named set.

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 direct guidance on when to choose this tool instead of siblings. An agent must infer from the name that qradar_list_reference_sets is for enumerating and this is for one specific set, but no explicit when/when-not guidance is 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?

There are no annotations, so the description carries the behavioral burden. It discloses that the operation retrieves data and returns a JSON string with specific fields, which is helpful. However, it does not mention error behavior for invalid/nonexistent IDs, permissions required, or rate limits. For a simple read operation 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 short and front-loaded with the main purpose. The Args and Returns sections are clean and scannable. The Args line is somewhat redundant with the input schema, but the overall structure is efficient and not bloated.

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 read-only tool with an output schema, the description provides enough to invoke it correctly: the resource, the parameter semantics, and the return format. It does not discuss not-found behavior or authorization, but those are relatively minor gaps at this complexity level.

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 defines rule_id as 'The ID of the rule to retrieve,' which adds a semantic label, but this largely restates the parameter name and the schema title 'Rule Id.' It does not explain where to find the ID, constraints, or how the ID maps to detection rules beyond that.

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

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

The description opens with a specific verb and resource: 'Retrieve full details of a specific detection rule by its ID.' This clearly distinguishes it from siblings like qradar_list_rules (which lists) and qradar_update_rule (which mutates). The word 'full' also signals a single-object lookup rather than a summary.

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 tool's intended use is clear: call it when you have a single rule ID and want full details. It does not explicitly name alternatives or state when not to use it, but the contrast with 'qradar_list_rules' is strongly implied by the wording 'a specific detection rule by its ID.'

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 states the read-only fetch behavior, requires a completed job, describes pagination, and specifies the JSON string return value. It does not mention rate limits or error behaviors, but for a simple retrieval this is 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 front-loaded with the main action and pagination, followed by a compact Args block and a one-line Returns note. There is no filler or redundant restatement of the schema.

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

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

The output schema covers return structure, while the description supplies the completed-job prerequisite, parameter meanings, and pagination semantics. It is slightly light on explicit sequencing guidance relative to qradar_execute_aql_search and qradar_get_search_status, but nothing essential for invoking it correctly is missing.

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

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

The schema has 0% description coverage, but the description's Args block documents all three parameters: search_id as the UUID, limit as record count with default 50, and offset as pagination start index. This fully compensates for the sparse 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 opens with a specific verb-resource pair, 'Fetch records from a completed Ariel search job,' and adds pagination to the scope. This clearly separates it from sibling tools like qradar_execute_aql_search and qradar_get_search_status.

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 'completed Ariel search job' qualifier gives a clear precondition: the tool should be used only after a search job has finished. It does not explicitly name alternatives or say when not to use it, but the intended workflow relative to sibling search tools is reasonably clear.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses meaningful behavior by listing the possible statuses (WAIT, EXECUTE, COMPLETED), progress percentage, and record count in the return. It does not mention error behavior or cancellation conditions, but for a status-check tool this is strong 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?

The description is appropriately brief and front-loaded. The purpose sentence states the action, and the Args/Returns format is compact with no filler, redundant phrasing, or irrelevant details.

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 status-check tool with an output schema, the description covers the essential details: what it does, the parameter meaning, and the return content. It could mention the relationship to qradar_execute_aql_search and qradar_get_search_results, but the tool is still callable without that gate.

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 only provides the type 'string' for search_id with zero schema coverage. The description compensates fully by stating that search_id is 'The UUID of the search job,' which is exactly the semantic information an agent needs to supply the right value.

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 ('Check') and resource ('Ariel search job'), and clarifies this is about 'status and progress' rather than results. This differentiates it from siblings like qradar_get_search_results, though it does not explicitly name that sibling.

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 usage context is implied by the purpose: use it to check the progress of an Ariel search job. However, there is no explicit guidance, such as 'poll this after qradar_execute_aql_search' or 'use qradar_get_search_results instead once status is COMPLETED.'

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 return format (JSON string with connection status, configured host, API test result), which is useful. However, it does not explicitly state that it is a read-only, non-destructive operation, nor does it mention error handling, timeouts, or failure behavior. For a health check, these are somewhat implied but not disclosed. Given the absence of annotations, this is a mild 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?

Two sentences with zero waste: the first states the purpose, the second states the return value. Front-loaded with the core function, perfectly sized for a simple health check.

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 health check, the description covers purpose and return format adequately. The existence of an output schema is signaled, and while we don't see it, the description's return note is sufficient. It does not mention error conditions or prerequisite steps, but these are not critical for a simple connectivity test. The definition is essentially complete for an agent 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, and the schema coverage is 100% (empty schema). The baseline for 0 params is 4; the description adds no param info because none exists, but it doesn't need to. No redundancy or missing param semantics.

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 ('verify') and resource ('connectivity to QRadar console, authentication validity, API reachability'). This clearly defines what the tool does and distinguishes it from all sibling tools, which are data operations (list, get, update, add, delete). 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 gives a clear context for when to use the tool: whenever you need to verify connectivity/auth/API reachability. It doesn't mention alternatives, but there is no sibling health-check tool, so no exclusion is necessary. The context is clear enough for an agent to decide to invoke 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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It clearly states the operation, the resource, and the output shape ('JSON string containing list of Ariel database names'), which fully characterizes this simple read-only tool. It omits minor details like error handling, but those are low-risk for a zero-parameter listing 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?

The description is two sentences with no filler: it states the resource, gives examples, and specifies the return type. The core purpose is front-loaded before the return detail.

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 listing tool with an output schema, the description is complete. It identifies the resource and the returned JSON string of database names, which is everything needed to 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?

The tool has zero parameters and the empty input schema is fully covered. With no parameters to document, the description need not add parameter details, and the 0-parameter baseline of 4 applies.

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

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

The description opens with a specific verb and resource: 'List all available Ariel databases in QRadar,' and gives concrete examples such as events, flows, and simarc. This makes the tool's scope unambiguous and distinguishes it from sibling tools that list other QRadar entities.

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

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

No explicit when-to-use or when-not-to-use guidance is provided, and no alternative tool is named. However, the wording 'list all available Ariel databases' makes the intended use case clear by implication: use it when you need the set of Ariel database names.

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 communicates a read-only search-and-list behavior and describes the returned JSON contents, but it does not address authentication requirements, API rate limits, or data freshness caveats. This is adequate but leaves some behavioral context implicit.

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 a clear one-line purpose, followed by a compact Arg list and a short Returns section. Every part contributes useful information, and the filter/sort examples are valuable despite their length.

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 moderate-complexity listing tool with no annotations and no schema descriptions, the description covers filtering, sorting, pagination, and return content. It doesn't mention auth prerequisites or explicitly route to qradar_get_asset, but these are minor gaps given the clear operation and the presence of sibling tool names.

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

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

The input schema has 0% description coverage, but the Args section fully documents every parameter with concrete AQL-style filter examples, sort syntax like '-risk_score_sum', and the meaning of limit/offset for pagination. The description fully compensates for the schema's lack of parameter guidance.

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 names a specific verb ('Search and list') and a specific resource ('assets discovered by QRadar SIEM'), and the Args/Returns sections make clear it returns a filtered asset list. It is easily distinguished from the sibling qradar_get_asset, which targets a single asset.

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 the list/search context by explaining filter expressions, sorting, pagination, and return shape, so an agent knows when to call it for multi-asset queries. It does not explicitly name alternatives or state when not to use it, but the intended context is clear enough from the operation and sibling names.

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 transparency burden. It discloses the return format ('JSON string') and the pagination mechanism via limit/offset, which is sufficient for a read-only list operation. It does not mention authentication or rate limits, but those are not critical for a simple list 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 concise and well-structured: a one-line purpose, then a clear Args block, and a Returns line. Every sentence adds value, and the format is front-loaded with the purpose.

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 list tool with three optional parameters and an output schema, the description covers the parameters and return type. No additional context is needed; the tool is self-contained and 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 input schema has 0% description coverage (only titles and defaults), so the description fully compensates by explaining each parameter: filter_expr with an example, limit as maximum count, offset for pagination. This adds significant 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 clearly states the tool lists Building Blocks (BBs) in QRadar SIEM, using a specific verb and resource. It distinguishes from sibling list tools (e.g., qradar_list_offenses, qradar_list_rules) by naming the exact resource type.

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 makes the usage context clear: use this tool when you need to list building blocks. It does not explicitly mention alternatives or exclusions, but the resource specificity and sibling names provide implicit guidance. A 4 reflects clear context without explicit when-not guidance.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns a JSON string of closing reasons and IDs, and 'List' implies a read operation. It does not mention authorization requirements, ordering, or any limitations, but for a simple parameterless listing tool this is reasonably transparent.

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 purpose and followed by return format. Every sentence earns its place and there is no fluff.

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 list tool with an output schema present, the description is essentially complete: it names the resource, gives examples, and states the return format. It could add a note about using this before closing an offense, but 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?

There are zero parameters and the schema already covers everything, so the baseline is 4. The description adds no parameter details, but none are needed.

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

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

States a specific verb ('List'), a specific resource ('all available offense closing reasons'), and gives concrete examples (False Positive, Resolved, Policy Violation). It is clearly distinct from the sibling list tools by naming the exact resource.

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 it: whenever closing-reason options are needed. However, it does not explicitly state when not to use it or mention any alternative sibling tools, so the guidance 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?

No annotations are provided, so the description carries full burden. It discloses the return format (JSON string with protocol types, status, last event times) and mentions filtering/pagination. However, it does not explicitly state read-only behavior, authentication needs, or error handling. The return format detail adds value, but a few more behavioral traits (e.g., no side effects) could be stated.

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 main purpose, followed by a clean Args section and a Returns section. Each sentence serves a purpose with no waste. The structure makes it easy for an agent to parse quickly.

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

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

The tool is a simple listing operation with three optional parameters. The description covers the purpose, parameters, and return value. With an output schema present and no annotations, the description is complete enough for an agent to call it correctly without missing critical information.

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 so thoroughly: filter_expr is explained with an example, limit and offset are described with defaults. Every parameter is covered meaningfully, going beyond the schema's type and default fields.

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 'List log sources registered in QRadar SIEM' with a specific verb (List), resource (log sources), and scope (QRadar SIEM). It also mentions optional filtering and pagination, clearly distinguishing it from the singular sibling 'qradar_get_log_source' and other list tools.

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 context by stating it lists log sources with filtering and pagination, but it does not explicitly mention alternatives or exclusions. It does not say 'use this instead of get_log_source when you need multiple sources,' but the purpose is clear enough that an agent would infer when 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?

No annotations are provided, so the description carries the behavioral burden. It does disclose the return format ('JSON string containing the list of offenses or error details'), but it does not explicitly state that this is a read-only operation, mention permissions, or describe any other behavioral constraints such as pagination limits.

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

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

The description is compact, organized into two clear sections, and every bullet provides actionable detail. There is no filler or redundant restatement of the tool name, and the key behavior is front-loaded in the first sentence.

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 simple list-operation nature, the fully documented parameters, and the presence of an output schema, the description covers everything required to call the tool correctly: filter syntax, sort pattern, pagination defaults, and the overall return shape.

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 thoroughly: filter_expr gets syntax examples, sort_by gets the '-' prefix convention, and limit/offset get defaults and semantics. This is exactly the kind of value beyond the raw JSON schema that agents need.

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: 'List offenses from QRadar SIEM'. It is clearly distinct from siblings like qradar_get_offense, which targets a single offense, and qradar_health_check, which is about system health. The scope is immediately understandable.

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 appropriate usage through 'optional filter, sorting, and pagination' and explains the argument purpose, but it does not explicitly state when to prefer this over alternatives like qradar_get_offense or when not to use it. The guidance is adequate but mostly implicit.

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 the behavioral burden. It clearly frames the operation as a listing call and states the output is a JSON string, but it relies on the verb 'List' to imply read-only behavior and does not disclose filter behavior, pagination semantics, or error/authentication 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 compact and well-structured: a front-loaded purpose sentence, clearly separated Args and Returns sections, and no filler. Every line earns its place by adding a parameter label, a default, or the return shape.

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 list operation with three optional parameters and an output schema, the description is mostly adequate: it names the resource, covers all parameters, and states the return shape. It falls short of complete because filter-expression semantics are absent and there is no pointer to related list tools, leaving selection under-informed.

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, but the Args lines mostly restate the parameter names and schema defaults. 'Optional filter expression' gives no syntax or operator details, and 'maximum number of maps'/'starting index' only lightly gloss what the names already imply.

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 uses a specific verb ('List') and names a concrete resource ('Reference Maps') with a clarifying gloss ('key-value lookups'). It does not explicitly differentiate the tool from siblings like qradar_list_reference_sets or qradar_list_reference_tables, so it misses full top-caliber 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?

There is no guidance about when to prefer this tool over related siblings such as qradar_list_reference_sets, qradar_list_reference_tables, or qradar_get_reference_map. The Args/Returns sections describe mechanics but provide no usage context, exclusions, or alternative-selection 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 carries the burden of behavioral disclosure. 'List' semantically implies a read-only operation, and the description specifies the return format as a JSON string with element type and TTL metadata. However, it does not explicitly state that no changes are made, nor mention authentication, rate limits, or error behavior, which are relevant for a networked API 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 compact and well-structured, with the main purpose stated first followed by a concise Args section and a brief Returns note. There is no filler or redundant restatement, and every line 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 tool's low complexity, the presence of an output schema, and full parameter documentation in the description, the definition is nearly complete. It lacks only explicit guidance on when to prefer this over sibling list tools and notes on possible response edge cases, but these are not critical for invoking this simple list 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 0%, but the description fully compensates by documenting all three parameters: filter_expr with an example, limit with its default, and offset with its purpose. This adds real semantic value beyond the bare schema definitions.

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 operation: 'List reference sets available in QRadar SIEM.' It identifies a specific verb and resource. It is differentiated from sibling operations like get/add/delete by the verb 'list,' but it does not explicitly distinguish itself from qradar_list_reference_maps or qradar_list_reference_tables, so it misses a bit of sibling differentiation.

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 guidance about when to use this tool versus alternatives. It does not mention that this is for querying reference sets rather than reference maps/tables, nor does it provide any exclusion criteria. The parameter defaults are explained, but not the decision context for selecting the 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?

No annotations are provided, so the description carries the full burden. It does reveal the operation is a listing operation and explicitly states the return format ('JSON string containing list of Reference Tables'), which is useful. However, it does not explicitly state that this is read-only, nor does it describe behavior for empty results, invalid filters, or pagination edge cases.

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 one-sentence purpose, an Args block, and a Returns line. There is no filler or repetition of the tool name, and the most important information 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 listing tool with three optional parameters and an output schema, the description is largely complete: it names the resource, documents all parameters, and states the return type. The main gap is the lack of filter-syntax detail and explicit read-only confirmation, but the output schema and the simple nature of the operation reduce the severity.

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 gives some meaning to all three parameters: filter_expr is an optional filter expression, limit is the maximum number of tables, and offset is the starting index for pagination. However, filter_expr remains vague—no filter syntax or format is described—so the added value is only partial.

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

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

The description opens with a clear verb and resource: 'List Reference Tables (multi-column tables) available in QRadar SIEM.' The parenthetical 'multi-column tables' helps distinguish this tool from sibling tools like qradar_list_reference_sets and qradar_list_reference_maps, so an agent can tell what resource is being listed.

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 intended use is implied by the name and the phrase 'available in QRadar SIEM,' but the description does not explicitly state when to prefer this tool over the sibling reference-set or reference-map tools, nor does it mention any exclusions or alternative tools. It provides clear context but no when-not-to-use guidance.

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

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

With no annotations provided, the description carries the behavioral burden. It states that the tool returns a JSON string containing matching rules and a count, and the verb 'List' makes the read-only nature clear. It does not discuss error behavior or authorization, but for a simple list operation this is reasonably transparent.

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 with separate Args and Returns sections. Every sentence contributes useful information, including parameter examples and default values, with no redundant 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 description is complete for a list tool: it covers purpose, filter syntax, pagination, defaults, and return shape. The presence of an output schema reduces the need to explain return structure further, and the resource type is named specifically enough to avoid confusion with sibling tools.

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 fully explain the parameters. It does so for all three: filter_expr includes concrete examples, and limit/offset state their defaults and roles in pagination. This adds real semantic value beyond the bare 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 uses a specific verb and resource: 'List correlation/detection rules in QRadar SIEM.' This clearly distinguishes it from siblings such as qradar_list_building_blocks and qradar_get_rule, which handle different resource types or granularity.

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 clearly identifies the operation as listing rules and mentions optional filtering and pagination, but it does not explicitly state when to prefer this tool over qradar_list_building_blocks or qradar_get_rule. Usage context is implied rather than explicitly routed.

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 the disclosure burden. It explicitly says the tool 'lists' hosts and returns a JSON string with servers, hostnames, IP addresses, component types, and status, which is useful behavioral context and implies a read-only operation. It does not discuss auth, rate limits, or large-result handling, but for a simple list-all tool this is a minor 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 very short and front-loaded: the first sentence states the action and scope, and the second lists the useful output fields. Nothing extraneous is included.

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 listing tool with an output schema present, the description is sufficient for an agent to select and invoke it. It makes the scope explicit and even helps interpret the response by naming the expected fields.

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 no parameters and the schema coverage is effectively 100% since there are no properties to document. The description adds a helpful note about the listing scope and output fields, matching the baseline of 4 for zero-parameter tools.

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: 'List all managed hosts / appliances'. It is clearly distinct from the sibling tools, which target rules, offenses, log sources, reference sets, and similar resources, so an agent can tell what this tool does without opening the schema.

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

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

The description implies when to use the tool (when you need an inventory of managed hosts/appliances in the QRadar deployment), but it does not explicitly discuss when to prefer it over alternatives such as qradar_health_check or a more specific list/get tool. There is no exclusions/when-not guidance, but the zero-parameter list semantics make the use case reasonably inferable.

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 this is a mutation, that closing_reason_id is required when closing, and that it returns a JSON string of updated offense details. However, it does not state whether omitted fields are preserved or cleared, nor any permission or error behavior, leaving some ambiguity for a write 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?

The purpose sentence is front-loaded and the Args/Returns structure makes scanning easy. Minor redundancy exists because status values are given twice (in the intro and in the Args list), but the overall length is appropriate for six parameters.

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 six-parameter mutation with no annotations, the description is largely complete: it explains all parameters, the conditional closing-reason requirement, and the return format. It is slightly incomplete on partial-update semantics (whether omitted fields are unchanged) and does not mention error cases, but an agent has enough to construct a valid call.

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 every parameter. It does: offense_id is identified as the ID, status lists allowed values, closing_reason_id is tied to closing, assigned_to is an analyst username, follow_up is a flag, and protected prevents automatic purging. This fully compensates for the bare 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 opens with a specific verb and resource ('Update an offense status... closing reason, assignment or flags') and enumerates the affected fields. This clearly distinguishes it from sibling update tools like qradar_update_rule by naming the offense resource directly.

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 context is clear: use this tool to modify an existing offense. It also provides a conditional usage rule ('Required if closing the offense') and points to the sibling qradar_list_closing_reasons for valid IDs. It does not explicitly state when not to use it versus read-only offense tools, but the mutation intent is unambiguous.

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 carry the behavioral disclosure burden. It does state the mutating action, mentions the audit trail role of the source parameter, and indicates a JSON return value. However, it does not disclose permissions, overwrite semantics, idempotency, or any error conditions.

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, with a one-line purpose followed by Args and Returns sections. Every sentence contributes useful information and the key action 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 four-parameter mutation with an output schema, the description is largely complete: it covers all parameters, the return type, and the audit trail behavior. It is only missing usage-routing guidance and a bit more behavioral caveat detail, but nothing required to make a basic call is absent.

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 by explaining every parameter: name is the target Reference Map, key is the lookup key, value is what to associate, and source is the audit trail label. This adds real meaning beyond the bare schema property 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 opens with a specific action and resource: 'Set or update a key-value entry in a Reference Map.' This clearly distinguishes it from sibling tools like qradar_get_reference_map, qradar_list_reference_maps, and qradar_add_to_reference_set.

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 intended use case is implied by the action phrase 'Set or update' and the mention of a target Reference Map, but there is no explicit guidance about when to choose this tool over alternatives like qradar_add_to_reference_set or qradar_delete_from_reference_set, and no exclusions are stated.

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

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

No annotations are provided, so the description carries the full burden. It states it updates rule settings but does not disclose what happens if rule_id is invalid, whether the update replaces all unspecified fields, or any permission requirements. The 'Returns' line mentions a JSON string but no error 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 highly efficient: one sentence for purpose, then an Args block, then Returns. Front-loaded with the action. No redundancy or filler; every section 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 tool's simplicity (3 params, one required, output schema exists), the description covers parameters and return type. However, it lacks usage context (e.g., prerequisites) and behavioral nuance (partial vs full update, error handling), making it adequate but not fully complete for an autonomous agent.

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

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

The description's Args section explains all three parameters with clear semantics: rule_id, enabled (True/False), and owner (new username). Schema only provides titles, so the description adds substantial meaning beyond the schema, achieving full coverage despite 0% schema description 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 the verb and resource: 'Update detection rule settings' and lists the specific actions (enable/disable, update owner). It distinguishes from siblings like list_rules and get_rule by being an update operation on rules, not offenses or reference sets.

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. Siblings like qradar_get_rule and qradar_list_rules exist, implying you'd first retrieve a rule, but this prerequisite is not stated. No exclusions or conditions are mentioned.

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