xsiam-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools are clearly differentiated by resource and action, but a few close pairs (healthcheck vs xsiam_health, dataset_* vs xql_* dataset tools, v1/v2 alert variants) could cause misselection.
Naming Consistency3/5
The naming is mostly snake_case with a domain prefix, but the ordering of action and resource varies (e.g., incidents_update_incident vs tags_agents_assign), and some tools have version prefixes or standalone names (healthcheck, get_risk_score), creating inconsistency.
Tool Count1/5
With 132 tools, the server is far beyond the recommended range and poses a significant navigation burden for agents, even with a discovery tool.
Completeness4/5
The tool set comprehensively covers the major XSIAM domains including incidents, alerts, endpoints, assets, XQL, scripts, and configuration, with only minor lifecycle gaps (e.g., no incident creation) that are reasonable given the platform.
Average 3.8/5 across 132 of 132 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
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, but it only restates the purpose and notes licensing and endpoint. It does not mention return format, pagination, rate limits, or potential side effects, leaving the agent without important behavioral context beyond what the tool name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise overall but redundant: 'Get all datasets' is immediately restated in the first sentence of the body. It includes useful info like license and endpoint, but the repetition wastes a sentence. The markdown formatting is clean but doesn't add semantic value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, an output schema, and any parameter documentation, the description is insufficient for an agent to understand the tool's full behavior. It lacks parameter semantics, return value expectations, and any operational caveats, making it inadequate for a tool with even moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter, request_data, has no schema description and zero schema coverage. The description does not mention it at all, so the agent receives no semantic information about what this parameter should contain or how to structure it. This is a critical gap for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all datasets' and elaborates with 'Retrieve a list of all the datasets and their properties,' which conveys a specific verb and resource. It doesn't explicitly distinguish from sibling tools like dataset_get_created_datasets, but the scope of 'all datasets' is reasonably clear from the name and text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The only usage-related information is the required license, which is a prerequisite rather than a contextual usage direction. The description lacks any mention of when this tool should be preferred over similar dataset-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It only mentions the license requirement and API endpoint, but does not disclose pagination behavior, sorting defaults, response format, or confirm that this is a read-only operation despite the 'Get' in the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose, followed by essential license and endpoint information. There is no fluff or redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimally adequate: it states the purpose and license requirement, and the schema provides rich parameter details. However, with no output schema and no annotations, the description does not explain the return value or pagination behavior, leaving some context gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for request_data, including sort, filters, search_from, and search_to. The description adds no parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all or a subset of attack surface rules' with a specific verb and resource scope. It is easy to understand the tool's function, but it does not explicitly differentiate from sibling get-type tools like get_risk_score or get_risky_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The only usage-related context is the required license, which is a prerequisite but not a decision guideline. It does not state exclusions, preferred scenarios, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility. It mentions license requirements, the API endpoint, and an example request body, but does not disclose response format, error behavior, potential side effects, or whether it is read-only beyond the verb 'retrieve'. The description adds little beyond what the name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and well-structured: a clear title, a brief explanatory sentence, license info, the endpoint, and an example. There is minor redundancy between 'Get Script Execution Results' and 'Retrieve the results...', but overall it is efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain what the response contains, but it does not. It does not clarify the relationship with sibling tools like get_script_execution_status or get_script_execution_results_files. The example covers only the request side, leaving the agent uncertain about the returned data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter, including a detailed description of 'action_id' and where to find it. The description provides an example request body that clarifies structure. Since the schema already documents the parameter well, the baseline is 3, and the example adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool retrieves the results of a script execution action, which is a specific verb-resource combination. It does not explicitly differentiate from sibling tools like scripts_get_script_execution_status or scripts_get_script_execution_results_files, but the term 'results' distinguishes it enough for basic understanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention that it should be used after running a script, nor does it explain differences from status or file retrieval tools. No exclusions or alternative suggestions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It reveals a required license and the HTTP endpoint but does not explicitly state read-only behavior, pagination, response format, or any side effects. The word 'Get' implies no mutation, but the lack of explicit disclosure for a POST endpoint is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: clear title, one-sentence purpose, license requirement, endpoint, and an example body. It is front-loaded with the core purpose and each piece adds relevant context, though slightly verbose with the repeated 'Get Scripts' heading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose, license, endpoint, and gives an example. However, it lacks explicit usage guidance and behavioral details like pagination or return value structure. Given the rich schema and lack of output schema, it is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The schema already describes all parameters and operators. The description's example request body provides a concrete illustration, slightly adding value beyond the schema, but not enough to elevate the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a list of scripts available in the scripts library,' combining a specific verb ('Get') with a resource ('scripts'). It is distinct from many siblings (e.g., scripts_run_script, scripts_get_script_code) but does not explicitly distinguish itself from the similar 'scripts_get' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It states what it does and includes a license requirement, but does not mention any exclusions or sibling tools. Usage is only implied by the purpose, not directly instructed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions the required license and endpoint, but does not disclose whether the operation is idempotent, whether existing tags are overwritten, what the response looks like, or any side effects. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise and well-structured with a title, a brief summary, license info, and an example. It could be slightly tighter, but the information is presented clearly and the example is valuable despite minor errors.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's nested request structure and the absence of both annotations and an output schema, the description doesn't provide enough context for an agent to fully understand the operation. Missing information about return values, error conditions, idempotency, or preconditions makes it incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. The example request body is present but has a malformed value ('<distribution_id' instead of '<distribution_id>') and does not explain the semantics of the tag or filters. The schema itself has detailed descriptions, but the textual description adds little useful parameter meaning beyond the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Assign one or more tags to one or more endpoints.' This is a specific verb+resource action and distinguishes the tool from its sibling, tags_agents_remove, which is for the opposite operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. The description doesn't mention tags_agents_remove or any conditions that would make this tool preferable. Usage is only implied by the action name, but not clearly contextualized.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 required 'Instance Administrator' permission and the special empty-value behavior for domain updates. It does not explain the effect on unspecified settings, reversibility, or error behavior, leaving important 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear intro, permission note, and endpoint line, followed by a detailed example body. The example is lengthy and somewhat repetitive with the schema, and the opening sentence repeats the tool name, but overall it is reasonably organized and not excessively verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex nested request body, no annotations, and no output schema. The description includes an example body and a special case, but lacks explanation of return values, error handling, or the meaning of many fields. This makes it insufficient for an agent to fully understand the tool's behavior without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 example request body shows the structure and placeholder values, but does not explain the meaning of most parameters. Only the current_domain_value and new_domain_value special case adds substantive parameter semantics, so the description falls short.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates existing authentication settings, using a specific verb and resource. It distinguishes from siblings by emphasizing 'existing' settings, though it doesn't explicitly mention alternatives like create or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context that this is for updating existing settings and includes a specific use case (updating default domain with empty values). It also notes required permissions. However, it does not explicitly contrast with sibling tools like authentication_settings_create or delete, leaving some ambiguity about when to choose this over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only mentions the required license and endpoint. It does not clarify whether this is a read-only operation, what the response contains beyond a few fields, whether pagination or rate limits apply, or what 'Response Action' means. The license requirement is useful, but other behavioral aspects are undocumented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and includes a structured layout with the endpoint, license, and example. The only redundancy is repeating 'Get triage presets' at the start and in the first line, but overall it is compact and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema or annotations, the description covers the basic purpose, the license prerequisite, a request example, and a list of fields returned. However, it omits details about the response format, potential errors, and how the result is packaged, leaving the agent with only a partial picture for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It provides an example request body with an empty request_data object, implying no parameters are needed, but it does not explain any optional fields or the structure of request_data beyond what the schema already shows. The example adds little meaning over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get all triage preset information including triage name, platform, description, created by, and triage type.' The verb 'Get' and the resource 'triage presets' specify exactly what the tool does, and it is distinct from sibling tools like triage_endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explain when to use this tool versus alternatives, nor does it mention any exclusions or conditions beyond the license requirement. It provides a required license and an endpoint but no guidance on the appropriate use case, so it fails to help the agent choose among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool initiates a script execution, requires a license, and supports Base64, but does not disclose the side effects (e.g., executing arbitrary code on endpoints), whether it is asynchronous, how results are retrieved, or any safety considerations. This is a potentially impactful action, and the description is under-transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and structured: a brief title, a one-sentence purpose, license requirement, API endpoint, and an example. The title repeats the tool name, but the example and endpoint info are useful. No unnecessary fluff, though the 'Run Snippet Code Script' line is redundant with the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the request format with an example and lists the required license, but does not explain the response, how to check execution status, error handling, or that the operation is asynchronous. Given the nested schema and lack of output schema, this is adequate for making a request but incomplete for understanding the full workflow. The sibling tools for status/results are not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by providing a concrete example request body that demonstrates how to structure nested objects (filters, snippet_code, endpoint_id_list). This clarifies the relationship between parameters and helps avoid malformed requests, going beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Initiate a new endpoint script execution action using provided snippet code.' This identifies the specific verb (initiate/run) and resource (snippet code script). It does not explicitly contrast with sibling tools like scripts_run_script, but the phrase 'using provided snippet code' distinguishes it from running a pre-existing script, earning a 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides prerequisites (required license) and a note about Base64 support, but it offers no guidance on when to choose this tool over alternatives. It does not mention that scripts_run_script should be used for existing scripts, nor does it state when to avoid this tool. No when-to-use or when-not-to-use information is included beyond the license requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior fully. It mentions the endpoint and permission requirements but omits the mutual exclusivity of xql_query_names and xql_query_tags. The example request body includes both fields simultaneously, directly contradicting the schema's note that they cannot be used together, which is misleading. It also does not explain the extended_view parameter's effect or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description has a clear structure with a summary, permission note, endpoint, and example. However, the example is long and misleading (showing both filters together), and it occupies space without adding accurate value. Could be tightened and corrected.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested request_data object, no output schema, and no annotations, so the description must compensate. It fails to describe the return format, error scenarios, pagination, or the mutual exclusivity of the filter parameters. The misleading example further reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters. It mentions filtering by names or tags, but the example incorrectly combines both in one body and does not mention the extended_view parameter. The description adds some meaning but is incomplete and partially misleading.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get XQL Queries' and 'Retrieve a detailed list of XQL query libraries' with a specific verb and resource. It naturally distinguishes from siblings like xql_library_insert and xql_library_delete by focusing on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving XQL query libraries and notes required permissions (Instance Administrator), but it does not explicitly contrast with sibling tools like xql_query or xql_start_xql_query. No when-not guidance is provided, only implied context from the verb 'Get'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions license requirements and a quota limit, but fails to disclose key behavior: that this likely starts an asynchronous query, returns an execution ID, and that results must be fetched separately. Saying 'Execute' may even mislead about the synchronous behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably structured with a link, note, license, endpoint, and example. It has minor redundancy ('Start' and 'Execute' repeat the same idea) but is otherwise focused and not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex async API with no annotations and no output schema, the description is incomplete. It omits the return value (execution ID), how to poll for results, and any timeouts or error cases, so an agent cannot fully understand the tool's behavior from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides an example request body with query, tenants, and timeframe, which helps visualize the format. However, it doesn't explain parameter semantics beyond what the schema already contains, and with 0% schema description coverage it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it starts/executes an XQL query, with a specific verb and resource. However, it doesn't explicitly differentiate from sibling tools like xql_query or xql_get_query_results, and the dual phrasing 'Start' and 'Execute' slightly blurs the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a link to XQL query API docs and a quota note (max 4 parallel queries), which gives usage context. However, it doesn't explicitly say when to use this tool vs. xql_query or how it fits into the query workflow, leaving usage largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral requirement: 'You must have **Instance Administrator** permissions to run this endpoint.' It also hints at the bulk nature via the filter example. However, it does not state that deletion is permanent or irreversible, which is important for a destructive tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action. The example request body is a useful addition that clarifies the request format, though the opening line is repeated ('Delete Correlation Rules' appears as title and first line), causing slight redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks critical context for a delete operation: it does not mention whether the deletion is permanent, what happens to dependent data, or what the API response looks like. With no output schema and minimal description, this is incomplete for a destructive, filter-based tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description adds no parameter explanations. The example request body shows the structure but does not explain the valid field values, operators, or nuances covered in the schema. The description fails to compensate for the low coverage, with no elaboration on the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete Correlation Rules' and specifies 'selected by filter', directly conveying the tool's purpose. This distinguishes it from sibling tools like correlations_get and correlations_insert, which handle retrieval and creation, respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool deletes by filter, implying a bulk operation, but it offers no explicit when-to-use or when-not-to-use guidance relative to alternatives. It only provides a permission prerequisite, not comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must communicate behavioral traits. It discloses the permission requirement and the endpoint path, but it does not describe whether the update is partial or full, what response to expect, or any side effects or failure modes. This leaves the agent with significant unknowns for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with two redundant statements: 'Update a syslog integration' and 'Update the details...'. The example body is long and duplicates schema information. While the permission note is useful, the overall structure could be tighter and more front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with no output schema and no annotations, the description should explain the update behavior (full vs partial), the response format, and potential errors. The schema covers field semantics, but the description omits these essential behavioral details, making it incomplete for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions for every field, including the protocol enum and security_info nuances. The description's example request body adds little beyond the schema since it merely repeats field names and values. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Update a syslog integration' and 'Update the details of the specified syslog integration.' It identifies the resource (syslog integration) and the action (update), distinguishing it from sibling tools like create, get, delete, and test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by stating the required permission ('You must have View/Edit Alert Notification permissions') and showing an example request, but it does not explicitly contrast with alternatives like create or test, nor does it state when not to use this tool. Usage is implied rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the permission requirement ('Instance Administrator') and shows the HTTP endpoint, adding some behavioral context. However, it does not state whether the deletion is permanent, if it is reversible, or what the response format will be. Without annotations, the description carries the burden and could be more transparent about the operation's consequences and return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise, with the key purpose stated upfront and supporting details (permissions, endpoint, example) organized well. The repetition of 'Delete a script' in the title and first line is slightly redundant, but the structure is otherwise clean and not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not describe the response or how to interpret success/failure. It also omits important context such as whether the deletion is permanent, if the script must be paused or unlinked, or any other prerequisites. The example is helpful but the inconsistency with the schema undermines completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds an example request body showing the filter structure, which helps, but it uses 'filters' (plural) while the schema defines 'filter' (singular), creating a direct contradiction that could mislead an agent. It also does not explain the allowed field values beyond 'name or ID' and the value property, leaving the parameter semantics partially covered by the schema instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete a script' and elaborates 'by filtering based on its name or ID,' clearly stating the action and the resource. It distinguishes itself from sibling tools like scripts_get_scripts and scripts_run_script by explicitly naming the delete operation and the filter mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over alternatives, nor any exclusions or prerequisites beyond the permission requirement. It does not mention related tools such as scripts_get_scripts for finding script IDs or scripts_insert for creating scripts, leaving the usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It adds practical details like required license, HTTP method, and an example request body. However, it does not disclose side effects, response format, or any error/edge-case behavior, which is a gap for a read operation without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose. The opening 'Get Script Execution Result Files' is a mild redundancy, but the remainder is concise and well-organized. The example body and license info are useful, and no wasted sentences are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and a nested request object, the description adequately explains how to construct the request but omits any reference to the response format or how the retrieved files are returned. This is a notable completeness gap, though the request-side context is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for all parameters, including action_id and endpoint_id. The tool description's example body reiterates the schema structure but adds no new semantic meaning beyond what is already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves files from a specific endpoint during script execution, using a specific verb and resource. It is distinguishable from the sibling tool scripts_get_script_execution_results by its focus on 'files' rather than results, though it does not explicitly name the sibling or contrast itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use guidance or alternatives. The context is implied by 'during a script execution,' but there is no exclusions or differentiation from similar script-related tools like scripts_get_script_execution_results or actions_file_retrieval_details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 reveals the license requirement, the POST method, and an example request, but it does not describe the response format, possible errors, or side effects. The phrase 'Response Action' is ambiguous, leaving significant behavioral traits undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a concise title, a one-sentence explanation, the license requirement, the endpoint, and an example request. Every part earns its place with no unnecessary repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema or annotations, the description covers the purpose, license, and request construction. However, it omits response details and error handling, leaving an agent uncertain about what to expect after the request. This is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already describes the only parameter 'group_action_id' as the 'Action ID of the selected request.' The description's example request body repeats the same structure without adding new semantic meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the status of requested actions by action ID, using the verb 'retrieve' and naming the resource. It is specific enough to convey the core purpose, though it does not explicitly differentiate from similar sibling tools like scripts_get_script_execution_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the required license, the HTTP endpoint, and an example request body, but it does not explicitly state when to use this tool instead of alternatives or mention any exclusions. The guidance is present but implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the effect (enable/disable) but does not disclose side effects, permissions, idempotency, or response behavior. The bulk-update nature and POST endpoint are mentioned, but no deeper behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a title, one-sentence summary, endpoint, and example. The example is useful and not redundant. Minor redundancy between the title and first sentence slightly reduces efficiency, but overall it is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested request_data object, lack of annotations, and no output schema, the description is incomplete. It provides an example but does not explain return values, error handling, scope of the bulk update, or whether the operation replaces or adds to existing settings. This is insufficient for a mutation tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 example request body illustrates the structure of request_data, including test_names and status, and shows the enum values for status. However, it lacks explanations of each parameter's full semantics, such as whether test_names is required or how multiple items are handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Enable or disable vulnerability tests.' This is a specific verb+resource combination that distinguishes it from sibling tools like assets_get_vulnerability_tests, which is a read operation. The endpoint and example further clarify the bulk-update nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the example request body, showing how to enable/disable test names. However, it does not explicitly state when to use this tool vs. alternatives, nor does it mention exclusions or prerequisites. Usage is implied but not directly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It adds useful context: required licenses, the HTTP endpoint, and the 100-ID limit. However, it does not describe the response format, error handling, or behavior when some IDs are invalid, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a title, description, license note, endpoint, and example. It is slightly redundant by repeating the title as the first line, but each section earns its place and the content is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with one parameter and no output schema, the description covers the input syntax, limits, and prerequisites. However, it fails to distinguish this tool from the similarly named sibling 'assets_get_external_ip_address_ranges' and does not explain what the returned details contain, leaving completeness gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the parameter fully (100% coverage). The description adds value by specifying the 100-ID limit and providing a concrete example request body, which clarifies the expected structure beyond the schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets external IP address range details based on range IDs. It specifies the resource (external IP address range) and the action (get), but does not explicitly distinguish it from the sibling tool 'assets_get_external_ip_address_ranges' (plural), which may list all ranges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions required licenses and a batch limit (up to 100 IDs), but provides no guidance on when to use this tool instead of alternatives. It does not mention the plural sibling tool for listing all ranges or other asset-related tools that might overlap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must reveal behavioral traits. It discloses that responses are concatenated with AND, max result set size is 100, and offset is zero-based. However, it omits permission requirements, error handling, and details about the return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a title, bullet points, and an example. It is slightly repetitive ('Get Audit Management Log' appears twice) but each substantive part earns its place, especially the example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested request_data object, the schema provides rich detail, and the example further clarifies usage. However, with no output schema, the description does not explain return values or response structure, leaving some context incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 100% of parameters, and the description adds useful semantics: the AND condition, max result set size, and offset behavior. The example request body illustrates how to structure the nested request_data, adding practical value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get audit management logs', specifying the verb and resource. It is distinct from sibling tools like audits_agents_reports, though it does not explicitly highlight what makes management logs unique. The name itself is descriptive enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 mentions that OR is not supported and result limits, but gives no context about when this tool is the appropriate choice among audit-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It does mention license and environment constraints, but for a destructive delete operation it fails to disclose permanence, side effects on the underlying BigQuery table, or any post-deletion consequences. This is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably compact but contains redundancy: 'Delete an XQL user dataset' appears twice in the first two lines. The license and environment lines add necessary context, but the repeated opening reduces conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with no output schema, the description includes critical license and environment constraints. However, it does not explain side effects, error behavior, or how this tool differs from the similar 'xql_delete_dataset' sibling, leaving it minimally adequate rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description itself provides no parameter guidance, but the nested schema includes descriptions for 'dataset_name' and 'delete_underlying_bq_table'. Although the context signal reports 0% schema coverage at the top level, the visible schema offers adequate parameter semantics, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Delete') and the resource ('XQL user dataset'), and adds a scope qualifier ('created by the Cortex SDK'). However, a sibling tool 'xql_delete_dataset' appears to target the same or similar operation, and the description does not explicitly differentiate between them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear execution context: required license tiers and the restriction that the API is only applicable from within the XSIAM Notebook environment. It stops short of naming alternatives or explicit when-not-to-use scenarios, so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It discloses a license requirement (a form of access context) and the endpoint, but does not explicitly state that this is a read-only operation with no side effects, nor describe response behavior. It provides some context beyond the bare purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action, but the opening 'Get Tenant Info' is redundant with the following sentence 'Get your tenant license information.' The structure with license and endpoint info is efficient, earning a high score despite minor redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation, the description provides essential purpose and a key prerequisite, but omits details about the 'request_data' parameter and response format. Since there is no output schema, some return value explanation would improve completeness, yet the tool's simplicity keeps it minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'request_data' with 0% description coverage, and the description does not mention or explain it. Since schema coverage is low, the description should compensate, but it offers no guidance on what to pass in this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get your tenant license information' with a specific verb and resource, unambiguously identifying the tool's purpose. It distinguishes this tool from all sibling tools, none of which relate to tenant license info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a required license (Cortex XSIAM Premium/Enterprise/Enterprise Plus) as a precondition, but does not explicitly state when to use this tool or mention alternatives. Usage context is implied rather than clearly specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only mentions the required license and the dataset type. It does not disclose side effects, error conditions, return values, or whether the operation is idempotent. For a mutation tool, this is a significant lack of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with a clear title, one-sentence summary, license requirement, and API endpoint. There is no wasted text, and the most important information appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested request_data, no output schema, no annotations), the description is incomplete. It omits expected response behavior, error handling, prerequisites beyond license, and any guidance on the schema structure. It is minimally adequate for a simple read, but for a mutating dataset operation it needs more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the top-level parameter, and the description only says 'with the specified name and schema,' missing explicit mention of dataset_type and schema format details. The schema itself provides some nested descriptions, but the description does not compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: "Add a dataset of type `lookup` with the specified name and schema." This is a concrete verb and resource, and it distinguishes itself from sibling dataset tools (e.g., xql_get_datasets, xql_delete_dataset) by emphasizing the 'lookup' type and the creation aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a required license, which is a clear prerequisite, but it does not explicitly say when to use this tool versus alternatives or mention any exclusions. Usage is implied (add a dataset), but no comparisons to sibling tools are offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the burden of disclosing behavioral traits. It adds the required license (Cortex XSIAM Premium or ASM Add-on) and the 20-ID limit, which are useful. However, it does not explicitly state that the operation is read-only (though 'Get' implies it) or describe what fields are returned, which is a notable gap given no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, starting with a clear title, then a concise two-sentence explanation, followed by licensing and endpoint details. It is front-loaded and avoids fluff, though the second sentence partially duplicates the schema's parameter description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool, the description covers the core purpose, ID limit, license, and endpoint. However, without an output schema, it omits any information about the response structure or what 'details' are returned, leaving the agent uncertain about what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter semantics beyond what is in the schema; it repeats the 20-ID limit already present in the website_id_list description. The license and endpoint details are not parameter-related.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('Website Details') with a specific scope: 'specific websites based on website IDs.' It distinguishes from list-style tools like assets_get_external_websites by implying lookup by ID, but it does not explicitly name alternatives, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than explicit: the description says you can submit IDs, suggesting you use it when you have known website IDs. However, it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention any alternatives, such as assets_get_external_websites, for listing websites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 disclose an important caveat: a success response only means the request reached endpoints, not that the file was quarantined if not found. However, it omits other behavioral details like permissions, reversibility, or side effects, and includes confusing filtering notes that are irrelevant to this endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is cluttered with irrelevant information about 'When filtering by multiple fields' and 'Offset is the zero-based number of incidents' which appears to belong to a different API (incidents). This distracts from the core purpose and adds unnecessary content. The example is helpful but the extraneous notes harm structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested request_data and no output schema, the description provides a working example and a key success-caveat note. However, it does not explain the response body, error handling, or permissions, and the irrelevant filtering/offset text reduces overall completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The example request body provides useful structural context for request_data. However, the filtering notes about AND conditions and offset are not aligned with the schema (only endpoint_id_list filter exists) and may mislead parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Quarantine file on selected endpoints.' It specifies a concrete verb ('quarantine') and resource ('file on selected endpoints'), and differentiates from siblings like endpoints_isolate (isolate endpoint) and endpoints_restore (restore). The limit of 1000 endpoints adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for quarantining files on specific endpoints, but does not explicitly mention alternatives or when not to use it. There is no direct comparison with quarantine_status or endpoints_isolate, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the required license, HTTP method (POST), and filtering behavior (AND, max 100, offset). However, it omits side effects, response format, or whether the action is asynchronous. Since no annotations are provided, the description carries the full burden and only partially meets it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description starts with a clear one-line purpose but then includes detailed filtering notes that seem tangential to the restore action. It also includes license and example sections, making it somewhat cluttered. It is structured but could be tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, so the description should describe the response or outcome. It does not mention what happens after the restore is executed, how to check status, or error handling. The filtering notes appear irrelevant to restore, further reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all parameters (100% coverage), setting a baseline of 3. The example request body adds a concrete usage example but does not explain the optional parameters beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Restore a quarantined file on a requested endpoints,' providing a specific verb and resource. This distinguishes it from sibling tools like endpoints_quarantine and endpoints_isolate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage for restoring quarantined files but does not explicitly state when to use this tool vs alternatives such as endpoints_quarantine. The filtering notes and license provide context but no direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 endpoint, required license, and UI location, but does not mention permissions, reversibility, idempotency, or response behavior. For a mutating action, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a purpose statement, UI location, license requirement, endpoint, and example body. It avoids unnecessary fluff, though the initial 'Block List Files' header is somewhat redundant with the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (nested object, no output schema) and lack of annotations, the description covers prerequisites and provides an example, but it omits success/error behavior and how this tool relates to the allowlist sibling. It is minimally viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents each parameter. The description adds an example request body that reinforces parameter structure but does not provide new semantic meaning beyond what the schema already states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add files which do not exist in the allow or block lists to a block list.' This includes a specific verb (add), a resource (files / block list), and a scope condition, distinguishing it from the sibling hash_exceptions_allowlist tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for blocking files and provides a precondition (files must not already be in allow/block lists), but it does not explicitly mention when not to use it or alternatives such as the allowlist tool. Context is clear but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for disclosing behavioral traits. It only states the operation's name and license requirement—it does not mention what the response includes, whether the operation is read-only, or any side effects. This is insufficient for a health-check tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written: a title, a one-sentence explanation, license requirements, and the endpoint. Every element is meaningful and there is no redundancy. It is front-loaded for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter tool, the description includes license and endpoint but omits the response format or what 'health check' actually returns. Since there is no output schema, the description should compensate, but it does not. This leaves the agent uncertain about the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema covers 100% of nothing. The description correctly does not add parameter details because none exist. Per the rubric, this merits a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as performing a health check of the Cortex XSIAM environment with a specific verb and resource. It distinguishes itself from general management tools but does not differentiate from the sibling tool 'xsiam_health', which appears to serve a similar function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the required license as a clear precondition for using the tool. However, it offers no guidance on when to prefer this tool over alternatives like 'xsiam_health' or when not to use it. There are no exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the required permission and the endpoint, which is helpful. However, it does not state that deletion is irreversible, what the response looks like, or how filtering behaves (e.g., AND/OR logic). This is a mutation tool with no safety annotations, so more transparency would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise and front-loaded with the core purpose, then permission, endpoint, and example. The example block is useful for a nested filter parameter, but there is minor redundancy between the title and the first sentence. Overall, it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with a nested filter schema and no output schema, the description does not adequately explain response behavior, reversibility, or the semantics of multiple filters. The provided example is inconsistent with the declared schema, leaving important gaps for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 provides an example request body showing structure, but the example uses 'field: rule_id' which is not in the schema's enum, and 'extended_view' is not defined in the schema at all. This is misleading rather than helpful, so the description fails to add meaningful parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete Indicators (IOCs)' and restates 'Delete IOCs selected by filter', using a specific verb and resource. It clearly distinguishes this from sibling tools like indicators_get or indicators_insert by focusing on deletion via filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to delete IOCs matching a filter and states required permissions ('Instance Administrator'), but it does not explicitly contrast this with alternatives or mention when not to use it. The purpose itself provides the context, so it is acceptable but not strongly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 does not explicitly state that this is a read-only operation without side effects, nor does it mention rate limits or what happens on invalid input. The only behavioral hint is the POST method and license requirement, which are not sufficient for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: a one-sentence purpose, license line, API endpoint, and an example. Each section is relevant and no unnecessary information is included. The title slightly overlaps with the first sentence, but the added detail ('full definitions', 'specific script') justifies the repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, one-parameter retrieval tool, the description covers the essential invocation details with a clear example. However, it lacks information about the return value (despite no output schema) and does not address potential errors or edge cases. This makes it minimally adequate but not fully complete for autonomous usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete documentation of the single parameter (request_data with script_uid). The description adds a concrete example request body, which helps agents understand the exact expected structure. This goes beyond the schema's existing coverage, though it does not introduce new parameter-level details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the full definitions of a specific script in the scripts library,' specifying a distinct verb (Get) and resource (script metadata/definitions) with a specific scope. This distinguishes it from sibling tools like scripts_get_script_code or scripts_run_script, which target different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes license prerequisites and an API endpoint, but provides no guidance on when to use this tool versus alternatives like scripts_get_scripts or scripts_get_script_code. It does not mention any exclusions or alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 a license requirement and the API endpoint/method, which is useful. However, it does not explicitly state that this is a read-only operation, nor does it mention pagination behavior or that an empty request returns all results. These are important behavioral traits for a listing tool, though the 'Get' verb partially implies read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. The header 'Get All Websites' is somewhat redundant with the first sentence, and the endpoint information could be considered extra, but overall it is efficient with no significant wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain what is returned, but it only says 'complete or filtered list' without specifying the fields or structure of each website record. It also does not provide examples or guidance on using the complex filter and pagination parameters, leaving significant gaps for such a data-rich tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline of 3 applies. The description does not add any parameter-specific meaning beyond what the schema already provides, but it is not required to since all parameters are fully documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a complete or filtered list of your public-facing websites.' The verb 'Get' is specific and the resource 'public-facing websites' is unambiguous. The plural 'websites' distinguishes it from the singular sibling tool 'assets_get_external_website', and the separate 'services' and 'last_external_assessment' tools have different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving website lists but provides no explicit usage guidance or mention of alternative tools. It states a required license, which is a prerequisite rather than a usage condition, and does not say when to use this over other asset tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits: results are concatenated using AND condition, maximum result set size is 100, offset is zero-based, and a specific license is required. However, it does not describe the return format, error behavior, rate limits, or whether the operation is read-only. Since there are no annotations, these omissions leave gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the main purpose. It uses concise bullet points for key constraints, lists license requirements, and includes an API endpoint reference. The example request body is lengthy but directly useful, earning its place. No unnecessary filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers request-side details, including pagination, filters, sorting, and an example. However, since there is no output schema, it should describe the return structure to help the agent process results. It does not mention response fields, error codes, or how to handle empty results, leaving the description incomplete for full end-to-end invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter `request_data`, so the baseline is 3. The description adds value through a detailed JSON example that illustrates how to structure sort, filters, and pagination fields, making the abstract schema more concrete and actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Gets a list of filtered endpoints.' It names a specific verb and resource and provides the API endpoint. However, it does not explicitly differentiate this tool from the sibling tool `endpoints_get_endpoints`, which likely has a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a filtered list of endpoints, but it does not provide explicit guidance on when to use this tool versus alternatives such as `endpoints_get_endpoints`. It mentions constraints like AND condition and max result set size, which indirectly clarify usage, but no direct alternatives or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses operational details such as the API endpoint, required licenses, and a 1000-endpoint limit, plus a concrete request example. However, it does not describe the behavioral consequences of isolation (e.g., network disconnect, reversibility), which is a significant gap for a security action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a short title, one-sentence summary, required license, API endpoint, and a single illustrative example. Every element earns its place; the JSON example is valuable without being excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested request_data object and no output schema. The description provides a comprehensive example and key operational context (license, limit). However, it does not explain what the response looks like, whether it returns an action ID, or the side effects of isolation, leaving some gaps in operational completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema itself. The description adds a JSON example showing the structure for isolating multiple endpoints via filters, which reinforces understanding but does not add new parameter meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool isolates one or more endpoints in a single request, with a specific verb ('isolate') and resource ('endpoints'). It also notes a 1000-endpoint limit and the API endpoint. However, it does not explicitly distinguish itself from sibling tools like endpoints_quarantine or endpoints_unisolate, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for isolating endpoints and provides a required license and an example request body, but it lacks explicit guidance on when to use this tool versus alternatives or when not to use it. No exclusions or comparison with other endpoint action tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 required permissions but does not explain whether the test sends data, validates certificates, saves anything, or what the response indicates. This leaves significant ambiguity about the tool's side effects and outcome.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise, with a clear title, one-sentence purpose, permission note, endpoint, and a full example. The example is long but directly useful, with no filler sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the schema thoroughly covers parameters, the description lacks information about return values (no output schema) and the exact behavior of the test (e.g., whether it attempts a network connection or sends a test message). For a tool with no annotations and no output schema, this is a meaningful gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions for every field, so the baseline is 3. The example request body illustrates the structure but adds no new semantic meaning beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Tests a syslog integration's validity' with a clear verb and resource. It distinguishes the tool from sibling syslog tools (create/update/get/delete) by emphasizing the testing action. The example request body further clarifies the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for testing syslog integration validity and includes a permission prerequisite. It does not explicitly mention alternatives or when-not-to-use, but the context is strong enough to guide an agent, giving it a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It mentions the maximum result limit of 1000 ranges and required licenses, which are useful. It also provides an example request body. However, it does not describe the response format, pagination behavior beyond offsets, or error handling, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear one-sentence summary, followed by key notes (limit, all/filtered, license), endpoint, and an example. The example is somewhat long but directly useful. No redundant or filler content, 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The request side is well covered by the schema and example, including filters, sorting, and pagination. However, the absence of an output schema means the description should explain what the response looks like, but it does not. The tool has a nested request structure, and while the example helps, the lack of return value information is a noticeable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already includes detailed descriptions for all parameters (100% coverage), so the baseline is 3. The description adds an example request body that demonstrates the filters structure, but it does not explain the meaning beyond what the schema provides. The example is helpful but not transformative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Get') and resource ('External IP Address Ranges'), with 'all' and 'list of all' explicitly differentiating it from the singular sibling tool. The additional phrase 'filtered by business units and organization handles' adds scope clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The note about retrieving all vs filtered results gives some usage context, and the required license is a prerequisite. However, there is no explicit guidance on when to use this tool over its sibling (e.g., assets_get_external_ip_address_range) or any exclusion criteria. The usage is implied rather than directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It usefully discloses the required Instance Administrator permission and the POST endpoint URL, which adds behavioral context beyond the name. However, it does not explicitly state that the operation is read-only, has no side effects, or explain response structure, pagination, or error behavior. It provides some transparency but leaves important behavioral traits undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is mostly efficient, but it contains redundancy: the first sentence 'Get authentication settings for all configured domains' and the second 'Get all the authentication settings for every configured domain in the tenant' essentially restate the same thing. The remaining content (permission, endpoint, example) earns its place. Removing the duplication would make it more concise, so it does not fully meet the 'every sentence earns its place' bar.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one empty request_data parameter, no output schema), the description is fairly complete: it states the purpose, the required permission, the endpoint path, and provides a concrete request body example. It does not describe the response format, but the purpose statement inherently implies that authentication settings are returned. For a simple getter with no annotations, this is a robust level of completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema shows a single request_data object with no properties and 0% coverage, so the description must compensate. It does provide an example request body (`{"request_data": {}}`), which indicates the expected structure and that an empty object is acceptable. However, it does not explain the meaning or purpose of request_data beyond the example, nor does it address the `additionalProperties: true` flexibility. The example helps but the semantic explanation is thin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with the resource 'authentication settings' and explicitly scopes to 'all configured domains' and 'every configured domain in the tenant' — a clear, distinct purpose. It differentiates from sibling tools like authentication_settings_update, create, and delete by being the read/get operation, and from get_metadata by targeting full settings rather than metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a notable usage guideline — the Instance Administrator permission requirement — and includes an example request body. However, it does not explicitly state when to use this tool versus alternatives such as authentication_settings_get_metadata or other getter tools, nor does it mention when not to use it. The usage context is implied rather than explicitly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It clearly indicates the destructive nature ('Delete') and notes the permission requirement, which is helpful. However, it does not mention whether deletion is permanent, what happens if no dashboards match, or what the API returns, leaving significant behavioral gaps for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized: a one-line summary, a source note, a permission warning, the endpoint, and an example. It is efficient and front-loaded with the core purpose. The example adds length but is useful and not redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested filters, multiple field types) and the absence of an output schema, the description provides essential context: what it deletes, permission requirements, and an example. However, it omits information about the response format, behavior on no matches, or any side effects beyond deletion, leaving the agent guessing about the outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is reported as 0% for the sole parameter, so the description must compensate. It provides a concrete JSON example showing the structure of request_data with filters, field, value, and operator. This adds meaning beyond the bare schema, but it does not explain all possible fields or operators, and the example only demonstrates EQ, so coverage is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete dashboards' and specifies it deletes dashboards retrieved by the Get dashboards API. This is a specific verb+resource combination that distinguishes it from other delete tools like distributions_delete or indicators_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (Instance Administrator permissions) and an example request body showing how to filter dashboards. However, it does not explicitly state when to use this tool versus alternatives or when not to use it, so it stops short of full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the required license and the HTTP endpoint, which are useful preconditions. The verb 'Get' implies a read-only operation, but the description does not mention response format, error behavior, rate limits, or side effects. It goes slightly beyond the minimum because of the license and endpoint, but remains incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a short one-line purpose, a license requirement, the endpoint, and a clear JSON example. It front-loads the core action and avoids unnecessary filler. The example is somewhat lengthy but directly useful, earning a high score without being excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, and the description does not describe the response structure or what the caller will receive (e.g., a URL string). The request parameters are well covered in the schema, and the example clarifies the request format. However, without any indication of the return format or possible error cases, the description is only partially complete for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema itself includes detailed descriptions for both parameters, especially package_type with all valid values. The tool description adds an example request body but does not explain the parameters beyond what the schema already provides. Despite the context signal suggesting 0% schema coverage, the actual schema clearly describes both parameters, so the description adds minimal extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the distribution URL for downloading the installation package.' It identifies the specific resource (distribution URL) and action (get), and distinguishes it from sibling tools like distributions_get_status or distributions_get_versions by focusing on the download URL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by requiring a distribution ID and package type, and it lists required licenses as a precondition. However, it does not explicitly compare with alternative tools or state when not to use this tool. The example provides concrete input guidance, but lacks exclusions or situational recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It mentions the required license and the endpoint, but does not disclose response format, error behavior, or explicitly state that it is a read-only operation (though 'Retrieve' implies it). This provides some behavioral context but leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise and well-structured with a heading, description, license note, endpoint, and example. It is front-loaded with the core purpose. The redundant title 'Get Risk Score' takes a small amount of space but is not detrimental.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter lookup with no output schema, the description covers the essential usage (example, license). However, it lacks return format details and does not differentiate this tool from siblings like get_risky_users or get_risky_hosts. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the 'id' parameter, including format details and constraints. The description adds an example request body but no new semantics beyond what the schema contains. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve the risk score of a specific user or endpoint in your environment, along with the reason for the score.' This uses a specific verb ('Retrieve') and identifies the resource ('risk score') and scope ('specific user or endpoint'), distinguishing it from sibling tools like get_risky_users and get_risky_hosts which likely operate on lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying 'specific user or endpoint' and provides an example request body. However, it does not explicitly mention when to use this tool versus alternatives or when not to use it. The license requirement is a useful prerequisite but not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral transparency burden. It discloses a key limitation (historic data not scanned) and a licensing requirement, which is valuable. However, it does not mention response format, error behavior, rate limits, or side effects beyond the insert operation. The example body provides some structural clarity but not full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized, with a clear opening line, a behavioral note, licensing info, and a formatted JSON example. The structure is logical and the code block aids readability. No redundant sentences, though the licensing info could arguably be moved to annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has nested objects and multiple parameters, but the schema covers many details. The description adds an example and a key behavioral note. However, the absence of output schema means the description should explain return values and error handling, which it does not. The missing 'severity' in the example also leaves a gap. Overall, it's moderately complete but not fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has descriptions for many fields but not all (e.g., 'class' has none), and schema coverage is only 50%. The description compensates partially by providing a complete example request body showing nested structure for 'request_data' and 'validate'. However, the example omits 'severity' which is required by the schema, potentially causing confusion. The description does not add direct parameter-level explanations beyond the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: inserting IOCs as JSON objects retrieved from external threat intelligence sources. It uses a specific verb ('Insert') and resource ('Simple Indicators, JSON'), and the name itself distinguishes it from sibling tools like indicators_insert_csv. The phrase 'Simple Indicators' is slightly ambiguous but overall the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool: when you have IOCs in JSON format from external sources. It also includes a caveat about XSIAM only scanning new data, which is useful for expectations. It does not explicitly mention alternatives like indicators_insert_csv, but the JSON-vs-CSV distinction is implied by the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It uses the read-only verb 'Retrieve' and includes license prerequisites, but it doesn't disclose response format, errors, or side effects. Adequate but with room for improvement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: purpose, license requirements, endpoint, and example. Every part serves a purpose and the example is valuable. It avoids unnecessary fluff, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a nested-parameter tool with no output schema and no description of the return value. The input is well-illustrated, but the quarantine status result format (e.g., possible values, structure) is not explained, which is a significant gap given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the schema itself has confusing swapped descriptions (file_hash says 'File path' and file_path says 'File hash'). The description provides an example body with placeholders but does not clarify the meaning of each field, making it insufficient to compensate for the misleading schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Quarantine Status' and 'Retrieve the quarantine status for specified files', giving a specific verb and resource. It distinguishes from sibling action tools like endpoints_quarantine by indicating this is a query/read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description identifies required licenses and provides an example request, making the intended usage clear. It does not explicitly name alternatives or exclusions, but the context around sibling tools (e.g., endpoints_quarantine) implies when this status lookup is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 that the tool adds or removes users from a role and requires a specific license, which is useful. However, it does not mention permissions, side effects, or whether existing assignments are replaced or appended. Given the mutation nature, more behavioral detail would be helpful, but the basic behavior is described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a title, behavior summary, license requirement, endpoint, and example. While the title is redundant with the first sentence, the content is purposeful and not excessively verbose. The example is useful for understanding the request format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation with a nested object parameter and no output schema. The description covers the request body and license, but does not describe the response format, error handling, or any post-conditions. This is a moderate gap for a tool of this complexity, so a score of 3 reflects the missing return behavior and caveats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for parameters, including descriptions for role_name and user_emails. The description adds an example request body that clarifies the expected structure, but it does not add significant meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Add or remove one or more users from a role.' This uses specific verbs (add/remove) and identifies the resource (users and roles), distinguishing it from sibling tools like rbac_get_users and rbac_get_roles which are read-only queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by describing the operation and the required license, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites beyond the license. The context is clear but lacks explicit guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It provides the endpoint, license requirements, and an example request body, but does not explicitly state that the operation is read-only, what it returns, or how errors are handled. The read-only nature is only implied by 'Get'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it starts with the purpose, then includes license and endpoint details, followed by an example. Though the example is somewhat redundant with the schema, it is useful for clarity and does not bloat the description excessively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter get operation, the description covers the purpose, license, and endpoint. However, it omits explicit usage alternatives, output format, and potential error responses. Given the lack of an output schema, these would be beneficial but are not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single parameter (script_uid) with a description, and the example JSON in the description matches the schema exactly. Since schema coverage is 100%, the description adds little beyond reinforcement of the structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the code of a specific script from the script library. This is a specific verb+resource and distinguishes it from sibling tools like scripts_get_script_metadata (metadata) and scripts_get_scripts (list). The title also reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a script's source code and lists required licenses, providing some context. However, it does not explicitly mention alternatives or when not to use it, leaving the guidance partially implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral context: the required license (Cortex XSIAM Premium/Enterprise/Enterprise Plus), the HTTP endpoint, and an example request body. However, with no annotations and no output schema, the description still omits any information about the response format or possible status values, leaving a gap in transparency for a read-like operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and organized with useful sections: summary, license, endpoint, and example. There is slight redundancy in the opening lines ('Get Script Execution Status' vs. 'Retrieve the status...'), but overall it is front-loaded and every substantive sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers purpose, license, endpoint, and an example. However, it lacks response detail and does not differentiate this status tool from the many related script tools (e.g., scripts_get_script_execution_results), which is particularly important given the absence of an output schema and the large sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameters, including the nested request_data.action_id with its source. The tool description adds a concrete example request body, but no additional semantic meaning beyond what the schema already provides, so it meets the baseline without exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose with a specific verb and resource: 'Retrieve the status of a script execution action.' This distinguishes the tool from related siblings like scripts_get_script_execution_results, which retrieves results rather than status. The tool name and description are aligned and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one needs script execution status, but it does not explicitly state when to use this tool over alternatives such as scripts_get_script_execution_results or actions_get_action_status. No exclusions or alternative guidance is provided, leaving the usage context inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the license requirement, protected dataset restrictions, and force behavior, but it omits other behavioral details such as idempotency, failure modes, or whether deletion is reversible. The provided details are useful but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence, a note, license info, endpoint, and an example. It is somewhat repetitive ('Delete a dataset' appears twice) but each section adds useful context without excessive fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations and no output schema, the description covers key constraints, dependencies, and license, but it does not explain the response format, error behavior for nonexistent datasets, or the exact request body structure. The example helps but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 mention 'dataset_name' via 'specified name' and 'force' for dependencies, and the example body illustrates usage. However, the example uses `"force": "yes"` while the schema declares boolean, and it does not explain the `request_data` wrapper structure clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a dataset') and specifies the resource ('dataset with the specified name'), plus lists supported dataset types. However, it does not differentiate from the sibling tool 'dataset_delete_dataset', so it is clear but lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not guidance: protected datasets cannot be deleted, and force is required only when dependencies exist. Also mentions required licenses. However, it does not mention alternatives or contrast with similar delete tools, falling short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the AND-only filtering condition, the maximum result set size (>100), zero-based offset semantics, and the Instance Administrator permission requirement. These are meaningful behavioral traits beyond what annotations provide, though it could also mention response structure or side-effect safety (though 'get' implies read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, with a clear structure: summary, bullet points for key traps, permission note, and an example. The opening line repeats the tool name, but overall the text is organized and each sentence contributes useful context. It could be tightened by removing the redundant title line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested request_data, filters, pagination, extended_view), the description provides core operational constraints (AND, offset, max size) and a permission requirement, but omits critical parameter syntax details. The example only shows extended_view, not how to construct filters or pagination. The schema fills some gaps, but the description alone is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is reported as 0%, so the description must compensate for parameter understanding. It only gives a high-level mention of 'filter results' and 'extended results' and an example with extended_view. It does not explain the filter fields, operators, or search_from/search_to parameters, which are essential for correct invocation. The example is minimal and does not cover the main use case of filtering.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Correlation Rules' and 'Return a list of correlation rules,' which identifies a specific verb and resource. It distinguishes from sibling tools like correlations_insert and correlations_delete by focusing on retrieval, and mentions filtering and extended results, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the general use case (list/filter correlation rules) but does not explicitly contrast with alternatives such as correlations_insert or correlations_delete. There is no when-not-to-use guidance or reference to sibling tools, so the agent gets a clear context but no exclusionary information. This is adequate but not rich.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the side effect that endpoints remain in the database after deletion, and provides a maximum limit of 1000 endpoints and required licenses. The 'Response is concatenated' text appears to be a copy-paste artifact, but overall it offers meaningful behavioral context beyond a simple action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and example, but includes a paragraph about filtering and offset that appears copied from a list/query tool and is not clearly relevant to a delete operation. The license and endpoint information are useful, but the extraneous filter details reduce overall conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, side effect, size limit, license, and an example. However, it lacks any information about the response format (e.g., whether it returns a list of deleted IDs or an error) and does not clarify whether the deletion is reversible through a restore tool. Given that this is a destructive operation with no output schema and no annotations, the description is adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It provides a concrete example request body showing the filters array with field, operator, and value, which helps the agent construct calls. However, it does not explain all possible filter fields or the relevance of the 'offset' note, and the 'response is concatenated' statement is confusing for a delete operation, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete Endpoints' and clearly states the action as deleting selected endpoints in the Cortex XDR app, with a specific verb and resource. It distinguishes itself from sibling tools like endpoints_restore or endpoints_quarantine by specifying deletion semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives license requirements and notes that endpoints still exist in the database, implying a specific use case. However, it does not explicitly state when not to use the tool or mention alternative tools, and the filtering/offset notes seem more relevant to a query than a delete operation. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 important behavioral constraints: up to 20 files, no more than 10 endpoints, AND condition only, and the required license. However, it includes an unrelated statement about 'Offset is the zero-based number of incidents' which is confusing and not relevant to file retrieval, and it does not explain the response format or action semantics, so transparency is only moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably structured with a heading, bullet points, and an example. However, the line about offset is extraneous and does not belong to file retrieval, so not every sentence earns its place. The length is acceptable but could be tightened without losing important details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool involves a nested request body with multiple fields, and no output schema is provided. The description covers limits, license, and an example, but it omits details about the response format, how to track the retrieval action, or any error conditions. The unrelated offset line adds noise. Overall, it is adequate but incomplete 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by providing a concrete example request body and clarifying the file limits and endpoint constraints, which helps the agent understand parameter structure beyond the schema. The irrelevant offset note is a minor distraction but does not undermine the overall helpfulness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Retrieve files from selected endpoints' with a clear verb and resource, and the tool name (endpoints_file_retrieval) aligns well. It distinguishes itself from sibling tools like endpoints_quarantine or endpoints_scan by focusing on file retrieval, and the example further clarifies the intended operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about when to use the tool (e.g., retrieve files from endpoints) and states a required license, which serves as a prerequisite. However, it does not explicitly mention alternative tools or when not to use this tool, leaving the usage guidance implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must fully carry behavioral disclosure. It correctly notes that filters combine with AND (OR unsupported) and specifies required licenses, but it also includes a confusing reference to 'Offset' that does not match any schema parameter. More importantly, it does not describe what happens after the scan is initiated (e.g., async behavior, how to track status).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the summary sentence is concise, the description includes an unrelated 'Offset' bullet and an example with redundant filter entries, making it longer than necessary. The structure is clear but not tightly edited.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema covers parameters well, but the description omits important context: what the response contains, whether the scan runs asynchronously, or how to check scan status. Given no output schema, this is a gap. The confusing offset reference also detracts from completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by providing a concrete example request body and clarifying that multiple filters are AND-combined, which is not explicitly in the schema. However, the irrelevant offset reference slightly undermines the added clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run a scan on selected endpoints,' providing a specific verb and resource. This distinguishes it from sibling tools like endpoints_abort_scan or endpoints_get_endpoints. 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended action explicit and provides licensing prerequisites, which helps an agent decide when to call it. However, it does not mention alternatives or when-not-to-use scenarios, leaving room for more explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 permission requirement and the HTTP endpoint, but it does not mention whether the deletion is permanent, what happens if the playbook is in use, or what the response contains. Some transparency exists, but gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the action. The permission note and HTTP endpoint are useful, and the example body adds value, though it could be trimmed. Overall, it earns its place without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with one nested parameter, the description covers the essential context: what it does, who can run it, and the HTTP endpoint. However, the filter/schema mismatch and the absence of any response/return value information leave gaps in completeness for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 provides an example body, but the example uses 'filters' while the schema defines 'filter', creating a mismatch. It also does not explicitly explain the 'field' and 'value' parameters, leaving the agent reliant on the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete a playbook'—a specific verb and resource—and immediately clarifies the deletion is by name or ID. This clearly distinguishes it from siblings like playbooks_get and playbooks_insert, which serve different actions on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that Instance Administrator permissions are required, which tells the agent who should invoke it. It provides clear context for the operation, though it does not explicitly mention when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It indicates the operation is a read (retrieve) and mandates specific licenses, but does not disclose error behavior, response structure, or side effects. The read-only nature is implicit but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with title, short description, license requirement, endpoint, and example. Every part earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single parameter and no output schema. The description explains the input but does not clarify what the response contains. For a simple retrieval, this is adequate but not complete, as return details are left unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds an example request body, which reinforces the schema but does not meaningfully extend parameter semantics beyond what the schema already describes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve information about one or more roles created in your environment', using a specific verb and resource. This distinguishes it from sibling RBAC tools like rbac_get_users, rbac_get_user_group, and rbac_set_user_role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving role information, and specifies required license editions. However, it does not explicitly compare with alternatives or state when not to use this tool, so it lacks explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It does disclose the required license, the 1000-endpoint limit, and the exact POST endpoint. However, it does not explain that this likely initiates an asynchronous action requiring subsequent status polling, nor does it describe the response shape, which is critical for an action endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well front-loaded: title, capability, license, endpoint, then a detailed example. Every section serves a purpose, and there is no filler, though the length is justified by the nested API format it needs to clarify.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description lacks critical operational context: it does not state whether the tool is synchronous or asynchronous, what the response contains, or how to retrieve execution status. The input schema covers request parameters well, but the post-invocation lifecycle is left unclear, which is especially important given the sibling status and results tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing a baseline of 3. The example request body adds practical meaning by illustrating how filters, script_uid, and parameters_values interrelate, and it references Get Script Metadata for parameter keys, going beyond the schema's static descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Run Script' initiates a new endpoint script execution action using a script from the script library, and adds a specific scope (up to 1000 endpoints). This distinguishes it from sibling scripts_run_snippet_code_script, which runs snippet code rather than a library script.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage requires an existing script_uid from the Get Scripts API, and the example shows how to structure a request. However, it does not explicitly say when to prefer this over scripts_run_snippet_code_script or mention that execution status should be checked via scripts_get_script_execution_status, so guidance is more implied than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral constraints (max 10 concurrent actions, license requirement, OS uniformity, online config) but does not explain what happens after initiation, return behavior, or side effects. Given no annotations, more detail would be beneficial, but the provided constraints add value beyond a simple action statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points, making constraints easy to scan. It is slightly redundant ('Initiate Forensics Triage' appears twice) but overall concise and front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations exist, so the description should explain expected outcomes or response format. It fails to mention whether the action is synchronous, what success/failure looks like, or what data is collected. It covers prerequisites but not the operation's results, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides clear descriptions for both parameters (agent_ids and collector_uuid), so schema coverage is effectively high. The tool description does not add parameter-level details, but the schema carries the semantic weight, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Initiate forensics triage for the specified agents' with a specific verb and resource. It distinguishes itself from sibling tools like 'get_triage_presets' which deals with presets rather than initiating triage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context including concurrency limits, license requirements, OS consistency, and configuration prerequisites. While it doesn't name alternative tools, it clearly defines when this tool is applicable and necessary conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 permissions and the endpoint but does not disclose that deletion is permanent, that multiple widgets can be deleted based on filters, or what the response contains. This is a significant gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear summary, followed by a permission note, endpoint, and a single illustrative example. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a nested request structure, the description is not fully complete. The example and permission note provide useful context, but the omission of irreversibility, bulk-delete semantics, and response format leaves gaps for an agent invoking a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 provides a concrete example request body with realistic filter values, illustrating the nested structure of request_data.filters. However, it does not explain the allowed enum values for field or operator beyond the example, leaving agents to rely on the misaligned schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' and resource 'widgets', immediately clarifying the action. The additional sentence 'Delete the widgets retrieved by the Get widgets API' distinguishes it from sibling tools like widgets_get and widgets_insert.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear prerequisite: 'You must have Instance Administrator permissions to run this endpoint.' The phrase 'Delete the widgets retrieved by the Get widgets API' implies a workflow with the Get API, though it does not explicitly name alternatives or when-not-to-use scenarios. The example request body further illustrates the intended usage with filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 results include details and the number of vulnerable services, but lacks information on pagination, sorting, or explicit read-only confirmation. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with a clear purpose sentence. The example request is relevant and well-formatted, though it adds a bit of length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no output schema. The description notes the response includes details, but doesn't clarify pagination, scope (whether for a specific asset or all assets), or any limitations. Enough for basic use but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers filter field and operator semantics, but the top-level request_data lacks description. The description adds an example request body, which helps clarify usage, but doesn't fully explain the purpose of request_data or all filter options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a complete or filtered list of vulnerability tests,' specifying the verb and resource. It distinguishes itself from sibling tools like assets_bulk_update_vulnerability_tests by focusing on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for retrieving vulnerability tests, including an example filter. However, it doesn't explicitly mention alternatives or when-not-to-use, only implying its use for listing rather than modifying.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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. It reveals important behaviors: responses are concatenated with AND logic (OR unsupported), max result set size is 100, offset is zero-based, and required licenses are specified. This goes well beyond a simple one-line summary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but each section contributes: summary, behavioral constraints, license, and an example. The example is substantial but earns its place by demonstrating parameter usage. It is structured with bullets and a code block, making it scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list/filter tool with no output schema, the description covers key request-side context: filtering semantics, limits, offsets, licensing, and an example. It does not describe the response format, but given the tool's simple query nature, the provided information is sufficient for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by including a detailed example request body that shows how to construct filters and sort, illustrating the semantics of nested parameters beyond the schema's textual descriptions. This helps an agent craft valid requests.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get agent event reports,' which clearly identifies the tool's function as retrieving audit/agent event reports. The resource is specific ('agent event reports'), distinguishing it from sibling tools like audits_management_logs, though no explicit comparison is made.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving agent event reports and includes license requirements as a prerequisite. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions like 'for management logs, use audits_management_logs.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the permission requirement and the endpoint, and the verb 'Get' implies read-only. However, it does not describe the response format, rate limits, or side effects, which is a gap for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, front-loaded with the primary purpose, and includes only necessary context (permissions, endpoint, example). No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description covers purpose, permissions, and an example request. However, without an output schema, it does not describe what metadata is returned, and no pagination or response details are given. For a basic read endpoint this is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single 'request_data' parameter with no documented properties and additionalProperties true. The description provides only an example with an empty object, adding no semantic meaning about what request_data should contain. Since schema coverage is 0%, the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get IdP metadata' and 'Get the metadata for all IdPs', specifying the verb, resource, and scope. This distinguishes it from sibling tools like authentication_settings_get_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context that this endpoint requires Instance Administrator permissions and uses a specific POST endpoint. However, it does not explicitly discuss when to use this over alternatives or mention exclusions, so it is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses prerequisite constraints (license, environment, table location) which is valuable behavioral context. However, it does not describe the mutation nature (create vs update), idempotency, side effects, or response format, leaving gaps for a state-changing operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using bolded notes for prerequisites and a clear lead sentence. There is minor redundancy between the first sentence and the second, but overall it is efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single nested parameter and no output schema, the description covers important prerequisites (license, environment, table location) but omits expected return values, error conditions, or whether the operation is idempotent. It is adequate but has clear gaps given the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% top-level coverage and only describes table_name within the nested object. The description adds the critical constraint that the table must be under public_access_user, which is not in the schema. It also reinforces the 'created by the user' requirement. However, it does not explain the request_data wrapper or provide format examples, so compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Define an XQL user dataset based on an existing BigQuery table created by the user.' This specifies the verb (define), the resource (XQL user dataset), and the source (existing BigQuery table), distinguishing it from sibling tools like dataset_get_created_datasets or xql_add_dataset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit operational constraints: the BigQuery table must exist under public_access_user, required license tiers are listed, and the API is only applicable from the XSIAM Notebook environment. This gives clear context on when the tool can be used, though it does not mention alternatives or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It reveals that the call is asynchronous, that receiving a distribution ID does not guarantee success, and that specific Cortex XSIAM licenses are required. This is materially helpful, though it omits details like error responses and 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and well-structured, with a clear heading, async caveat, license note, endpoint, and example. There is minor redundancy between 'Create distributions' and 'Create an installation package,' but it does not hurt readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex nested input schema, no output schema, and no annotations. The description only mentions an example with four fields and does not cover the full required set or clarify valid combinations for package_type, platform, deployment_platform, and version fields, leaving an agent under-equipped to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The example request body provides some concrete values, but it omits required nested fields such as deployment_platform, default_namespace, run_on_master_node, and run_on_all_nodes. The schema itself offers more detailed descriptions for package_type and platform, so the description adds limited value and could mislead an agent into constructing an invalid request.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Create an installation package' and 'Create distributions.' This clearly distinguishes it from sibling tools like distributions_delete, distributions_get_status, and distributions_get_versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly explains the async behavior and instructs the user to confirm success via the Get Distribution Status API. This gives practical guidance for the follow-up step, though it does not explicitly discuss alternative creation tools or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the required license, HTTP method, and endpoint, but does not disclose potential side effects (though it implies a read-only operation) or what the status response contains. With no annotations, the description carries the burden, and it provides only minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and appropriately front-loaded with the purpose. The license requirement, endpoint, and example are each relevant, though the example JSON block could be considered slightly verbose for a single-parameter API.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 output schema), the description covers the essential endpoint and example, but lacks return value information or behavior details. It's adequate but not fully complete for an agent to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The example request body demonstrates the expected structure with 'distribution_id', and the schema already includes a description for that parameter. The description adds no additional semantic meaning beyond the schema, so a mid-range score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get Distribution status' and 'Check the status of the installation package.' This is a specific verb+resource pairing that distinguishes it from sibling tools like distributions_create or distributions_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to use the tool (checking status of an installation package) and includes required license information. It doesn't explicitly mention alternatives, but the use case is well-defined and unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It states the core behavior (list all endpoints) and mentions a limitation (AND condition, OR not supported), but the AND condition is ambiguous and could confuse. It does not describe response format or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. It includes useful metadata (license, API path), though the AND condition note adds slight confusion. Overall, each sentence has a purpose, but the redundant title/description opening could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list endpoint, the description covers the core action and license prerequisite. However, it lacks details on response structure and pagination, and the AND condition is unexplained. Given no output schema, this leaves some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description does not need to elaborate on parameters, though the mention of an AND condition is not clearly tied to any parameter and could be seen as irrelevant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Gets a list of all of your endpoints,' which is a specific verb and resource. It distinguishes itself from the singular sibling 'endpoints_get_endpoint' by explicitly saying 'all.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly name alternatives or exclusion criteria. The usage is implied by 'all of your endpoints' and the license requirement provides some prerequisite context, but there is no direct guidance on when to choose this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must be self-sufficient. It discloses the required license, HTTP method (POST), and API path, which are useful access constraints. But it does not describe the response format, error conditions, or any side effects. The "Get" verb implies read-only, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat repetitive ('Get Policy' appears as a heading and is restated in the first sentence), but it is still compact and well-organized with a license note, API path, and example. Each section earns its place, though trimming the first line would improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter, the description conveys the request format and licensing but omits the response structure. Since there is no output schema, the absence of an example response or explicit statement of what is returned leaves a gap. The name and first sentence hint at the return value, but completeness would benefit from a response example.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only describes endpoint_id as 'Endpoint ID,' which is minimal. The description adds an example request body showing the nested request_data object, which clarifies parameter structure. However, it does not explain how to find the endpoint ID or its format, so the added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Get the policy name for a specific endpoint.' This uses a precise verb and resource, and distinguishes it from sibling tools like endpoints_get_endpoint or endpoints_get_endpoints, which likely return general endpoint details rather than policy names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it applies to a specific endpoint, requires an endpoint_id, and lists the required license tiers. It also shows an example request. However, it does not explicitly mention when not to use it or point to alternatives, so it stops short of full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 required license and the HTTP method, and provides an example request body. It does not mention side effects, return values, or that sending an empty alias deletes the existing alias (though that is in the schema). This is a moderate level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a title, license requirement, endpoint path, and a clear JSON example. It is not overly verbose and each section serves a purpose. The example is somewhat lengthy but valuable for quickly understanding the request format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested request_data structure and the absence of an output schema, the description provides an example but does not explain what the API returns, error cases, or the full range of filter options. The schema fills in some gaps, but the description itself is not fully complete for an agent to invoke the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 provides an example request body showing the structure of request_data, alias, and filters with field/operator/value. However, it does not explain the allowed filter fields, operators, or the meaning of context. The schema itself has detailed descriptions, but the description alone only partially explains the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Set an Endpoint Alias' and 'Set or modify an Alias field for your endpoints.' This uses a specific verb and resource, and it distinguishes itself from sibling tools like endpoints_get_endpoint or endpoints_isolate by focusing on alias/agent name updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (to set/modify an endpoint alias) and includes the required license. It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough for selection among the many endpoint-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 mentions the required license and that the response includes reasons for each score, but does not detail response structure, pagination, limits, or authentication requirements beyond the license. The POST method is noted, but that is more of an API detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loads the purpose with a clear one-line explanation. However, the line 'Get Risky Users' is redundant with the tool name, adding a small amount of waste. The license and endpoint information are useful and compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool without an output schema, the description conveys the core return value ('users with highest risk scores along with reasons'), plus license and endpoint. However, it leaves ambiguity about how many users are returned and whether they are sorted, and does not mention any filters or scoping options, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description correctly provides no parameter-specific information, matching the schema. Per the rubric, a baseline score of 4 is appropriate when no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of users with the highest risk score along with the reason affecting each score. This specific verb+resource combination distinguishes it from sibling tools like get_risky_hosts, which targets hosts instead of users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by stating the tool works 'in your environment' and lists required license (Cortex XSIAM Premium or Identity Threat Module), implying when it can be used. However, it does not explicitly compare to alternatives like get_risky_hosts or explain when to prefer one over the other, so usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 required license, the API endpoint, and provides an example request body. However, it does not mention side effects, reversibility, permissions, or response behavior beyond the vague 'Response Action' label. It gives some context but is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a short title, a clear one-line purpose, license info, endpoint, and a practical example. The title 'Allow List Files' is somewhat redundant with the following sentence, but the overall structure is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should provide more detail about expected responses or side effects. It explains how to call the endpoint and gives an example, but does not describe what the response looks like or what happens on failure. This is adequate for a simple action but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by including a full example request body that demonstrates the structure and typical values for 'hash_list', 'comment', and 'incident_id'. This goes beyond the schema descriptions and helps the agent understand how to construct a valid request.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Add files which do not exist in the allow or block lists to an allow list.' It uses a specific verb (add) and resource (files to allow list), and the presence of a sibling tool 'hash_exceptions_blocklist' makes the distinction obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a usage condition ('files which do not exist in the allow or block lists') but does not explicitly mention when to use this tool vs alternatives. It provides the required license, which is a usage constraint, but lacks explicit when-to-use or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses the permission requirement and shows an example, but doesn't state whether deletion is permanent, irreversible, or what happens to scheduled queries with invalid IDs. The example hints at batch deletion but more behavioral details would be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise, with a minor repetition of 'Delete a scheduled query' and 'Delete scheduled queries'. It effectively front-loads the purpose, then provides permission, endpoint, and example. The structure is clean and each section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but without an output schema or annotations, the description omits information about return values, error handling, or side effects. The permission note and example provide useful context, but a more complete description would mention the response format or irreversible nature of the delete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only one parameter (request_data) with 0% description coverage. The description compensates with an example showing an array of IDs, implying the parameter is a list of scheduled query identifiers. However, it doesn't explicitly define the format or semantics beyond the example, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a scheduled query' and 'Delete scheduled queries', identifying the specific action and resource. It distinguishes from sibling tools like scheduled_queries_list and scheduled_queries_insert by focusing on the deletion operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for use by stating the permission requirement ('Instance Administrator') and showing the endpoint. It doesn't explicitly mention when not to use or alternatives, but the usage context is clear enough for an AI agent to infer when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden. It discloses the mutation behavior (insert/update) and a required permission level. Yet it does not describe response behavior, error conditions, idempotency, or batch effects. The example body adds some context but leaves significant behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description starts with a clear summary, but the first two sentences are slightly redundant ('Insert or update scheduled queries' followed by 'Insert new scheduled queries or update existing scheduled queries'). The endpoint and example are useful and well-formatted. Overall it is efficient and well-structured for an API reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity with nested objects, but no output schema or annotations. The description provides the endpoint, permission note, and a concrete example, which covers request structure. However, it omits response format or return values, and does not clarify array semantics (e.g., whether multiple items are processed as a batch). These gaps reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (only one property has a description), so the description must compensate. The included example request body illustrates all required fields (query_definition_name, xql, timeframe, schedule) with concrete values and nested structure, adding meaning beyond the bare schema types. However, it does not explain field semantics like units for relativeTime or allowed trigger_type values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Insert or update scheduled queries'. This uses a specific verb (insert/update) and resource (scheduled queries), and is further clarified by 'Insert new scheduled queries or update existing scheduled queries.' It also provides the endpoint path, distinguishing it from siblings like scheduled_queries_delete and scheduled_queries_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by naming the operation and includes a permission prerequisite ('You must have Instance Administrator permissions'). However, it does not explicitly compare to alternatives or state when not to use it. The guidance is contextual but lacks explicit exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 discloses the Instance Administrator permission requirement and explains that extended_view includes additional fields that may change. However, it does not mention pagination, default sorting, or the structure of the response, leaving some behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loaded with the core action, followed by key details, permission note, and a helpful example. It is concise without unnecessary fluff, though the example block adds length, it is relevant and illustrative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested request_data parameter and no output schema. The description covers purpose, permissions, and provides an example, but it lacks information about response format, pagination, or edge cases like combining filters with list_ids. This is a moderate gap for a list endpoint with filtering capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides an example request body that demonstrates how to use list_ids, filters, and extended_view. However, it does not explicitly explain each parameter's semantics. The schema descriptions cover some fields, but the context signal indicates low schema coverage, and the description's example is the only additional guidance. It adds some value but is not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get scheduled queries' and 'Return a list of scheduled queries.' It specifies the resource (scheduled queries) and the action (list/get), and differentiates from siblings like scheduled_queries_delete and scheduled_queries_insert by focusing on retrieval with optional filtering and extended view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use this tool: to retrieve all or filtered scheduled queries, optionally with extended details. It does not explicitly name alternatives or exclusions, but the uniqueness of the list operation among siblings makes the usage clear. It also states the required permission, which helps in deciding applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It clearly indicates a delete operation and permission requirements, but does not disclose whether deletion is irreversible, mention side effects, or describe the response format. This is a moderate level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear heading, short explanation, permission note, endpoint, and example. The only redundancy is the repetition of 'Delete XQL queries' in the first two lines, but overall it is concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema or annotations, the description provides permission and an example but omits response details, error handling, and clarification of the filter exclusivity. It is usable but not fully complete for an agent to understand all behavioral outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the top-level parameter, so the description must compensate. It explains the two filter options and provides an example. However, the example includes both filters in one request, which contradicts the schema's note that they are mutually exclusive, and it does not clarify whether at least one filter is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete XQL queries' and specifies filtering by query names or tags. This distinguishes it from sibling tools like xql_library_get and xql_delete_dataset, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides important context by requiring Instance Administrator permissions and includes an example request. However, it does not explicitly contrast with alternatives or state when not to use this tool, so it falls short of full guideline clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the post-processing steps (download and unzip) and includes a curl example and license requirement. As there are no annotations, it carries the full burden and does so effectively, though it does not state safety characteristics like read-only or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is quite long but well-structured with headers, code blocks, and a numbered process. It contains practical details like the exact curl command, unzip step, and license, but a few phrases restate the workflow (e.g., 'Download the file' appears in both text and code comment).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description does a solid job by specifying the required endpoint, request example, license, and the response's key action (contains a file hash to download). It does not document error responses or exact output JSON, but the core workflow is clearly covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a 100% description coverage for the single parameter, group_action_id. The description adds an example body and clarifies the parameter's provenance ('according to the action ID'), but that information is largely redundant with the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'View the API required to call in order to download the file retrieved by the Retrieve File API request according to the action ID.' It identifies a specific resource (file retrieval details) and the key input (action ID). It does not explicitly compare to sibling tools, but the context of the Retrieve File workflow makes it distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after a Retrieve File API request, providing the required license and a concrete example request body. It lacks explicit when-not-to-use guidance or named alternatives, but the intended context is clear from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and discloses key behaviors: AND condition for filters (OR not supported), maximum result set size (>100, albeit ambiguously phrased), zero-based offset, and Instance Administrator permission requirement. It also provides an example request body. However, it does not describe the response format and contains minor typos/ambiguities ('incidents', '>100').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief intro, bullet points, permissions, and an example. It is somewhat redundant ('Get BIOCs' followed by 'Return a list of BIOCs') and has a typo ('incidents' instead of 'BIOCs'), but overall it is fairly concise and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description provides a good degree of completeness for a list-getter: it covers permissions, filter behavior, pagination (offset), size limit, and an example. However, it lacks response format details and has ambiguous wording ('maximum result set size is >100') and a copy-paste error ('incidents').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds some meaning beyond the schema by explaining the AND condition for filters and offset behavior, and provides an example request body. However, it does not explicitly map these concepts to parameter names (filters, search_from, search_to) and does not compensate for the undocumented top-level request_data parameter. Schema coverage is 0%, but the nested schema descriptions are detailed, so the description's added value is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get BIOCs' and 'Return a list of BIOCs.' It also distinguishes itself from sibling tools like bioc_insert and bioc_delete by focusing on retrieval, and mentions optional filtering and extended view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via 'You can return all BIOCs or filter results' and notes the permission requirement and endpoint path, but does not explicitly state when to use this tool over alternatives or provide any exclusion criteria. It gives context but lacks explicit guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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. It discloses the permission requirement and the upsert nature ('Insert or update'). However, it does not explain side effects, such as whether existing dashboards are fully replaced, what happens on missing global_id (though a note exists in the schema), or what the API returns. The large example provides structural guidance but not behavioral depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The prose portion is concise and front-loaded, with the action, permission, and endpoint clearly stated. The example is lengthy but earns its place as it illustrates a complex nested structure. No wasted sentences, though the overall length is substantial due to the example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with one nested parameter and no output schema, the description should explain expected return values, error conditions, and potentially point to related tools like dashboards_get. It mentions the source of data but does not describe the output or post-conditions. This leaves significant gaps for an AI agent to understand the full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0% and only one top-level parameter, the description compensates by providing a detailed example request body that illustrates the expected structure of request_data. It also clarifies that the data should come from the Get dashboards API. However, it doesn't explain each parameter's semantics explicitly, but the example is comprehensive enough to guide correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Insert or update dashboards'. It further clarifies the scope by specifying 'Add or update the dashboards retrieved by the Get dashboards API.' This distinguishes it from sibling tools like dashboards_get and dashboards_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for adding or updating dashboards and references the Get dashboards API as the source of the data. It also mentions the required Instance Administrator permission, giving important usage context. However, it does not explicitly state when to use this tool over alternatives like widgets_insert, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It provides the permission requirement and shows an example request body, but it does not disclose the return value, idempotency, duplicate handling, or error behavior. This is a moderate level of disclosure for a creation endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is not overly long but includes redundancy: 'Create a syslog integration' is immediately repeated as 'Create a new syslog integration.' The rest—permission, endpoint, and example—is useful, but the duplicate opening wastes space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has nested objects and protocol options, and the example covers a TLS case. However, with no output schema, the description does not explain what response to expect after creation, nor common error conditions. This leaves some practical gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, so the baseline is 3. The description adds a concrete example request body that illustrates real values and the nested structure, which helps clarify how the abstract schema fields are used in practice.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Create a syslog integration.' It distinguishes itself from sibling tools like integrations_syslog_get, update, delete, and test by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides the required permission ('View/Edit Alert Notification') and implies when to use the tool (to create a new syslog integration). It does not explicitly mention alternatives, but the context is clear enough for this create operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 useful context: required 'View Alert Notification' permissions and the POST endpoint path. However, it does not disclose pagination, response structure, or potential errors. For a read-only list operation, the permission and endpoint info is helpful but insufficient for full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and front-loaded with the core purpose. It includes a permission note, endpoint, and a concrete example in a compact format. The example adds a few lines but is relevant and doesn't feel like padding. Slightly less concise than a pure sentence but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 presence of a nested filters object, the description covers the key aspects: what the tool does, required permissions, endpoint, and example usage. There is no output schema, so the description does not detail the return value, but for a simple list operation, this is acceptable. However, a note about pagination or the response being a list of syslog servers would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 100%, baseline is 3. The description adds value by providing an example request body showing how to use filters with the 'name' field, which clarifies the expected JSON structure beyond the bare schema. This practical example helps the agent construct valid inputs, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all or filtered syslog servers' and elaborates with 'Get a complete or filtered list of syslog servers.' This specifies the exact verb (get), resource (syslog servers), and scope (all or filtered), which also distinguishes it from sibling tools like integrations_syslog_create, integrations_syslog_update, and integrations_syslog_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading syslog servers by saying 'Get all or filtered' and gives a permission requirement, but it does not explicitly mention when to use this tool versus the create/update/delete/test siblings. The contrast is implied by the verb 'get' but not directly stated, so some ambiguity remains about when to choose this over related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It discloses the permission requirement and the response format (YAML in ZIP). It does not mention edge cases like not-found or duplicate names, but for a read-only lookup, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and includes a permission note and an example. It is front-loaded with the main purpose. Minor redundancy exists ('Get a playbook' repeated) and the example block could be formatted more tightly, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, permission, return format, and an example, which is decent for a simple getter with one parameter and no output schema. However, it misses edge-case behavior (e.g., not found, multiple matches) and the example's key mismatch ('filters' vs 'filter') leaves a correctness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the filter.field enum with descriptions, so the description adds an example request body. However, the example uses 'filters' while the schema expects 'filter' (singular), which is misleading and could cause invocation errors. The description does not clarify the correct parameter structure beyond the schema, and the inconsistency is harmful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a playbook' and specifies the filtering by name or ID, with the unique output format of YAML in a ZIP file. This distinguishes it from sibling tools like playbooks_insert and playbooks_delete, which are write/delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for use: filtering by name or ID and returning a ZIP file, plus a required permission (Instance Administrator) and an example request. It does not explicitly mention when not to use it or alternatives, but it is the only getter among playbook tools, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavior. It covers key traits: response concatenation with AND (OR not supported), maximum result set size 100, zero-based offset, PCAP detection in PAN NGFW alerts, required licenses, and the ability to fetch all or filtered results. These details go well beyond a generic 'get' operation, though it does not describe error handling or the full response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a note, bullet points, example, and license info, but it is somewhat verbose. The legacy note and license requirements add context, yet some statements (e.g., 'Note: You can send a request to retrieve either all or filtered results') are redundant with the example and bullet points. It could be tightened without losing key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested request_data object) and the absence of an output schema, the description explains input constraints thoroughly (AND condition, max size, offset, PCAP, licenses). However, it does not describe the response format or fields returned, which is a notable gap. The legacy designation and pointer to v2 partially mitigate the incompleteness, but for a standalone tool, more detail would be needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides rich descriptions for all parameters (sort, filters, search_from, search_to). The tool description adds value through an example request body and clarifies offset is zero-based, plus the maximum result set. However, it does not systematically explain each parameter, and since schema coverage is listed as 0%, the description only partially compensates by relying on the schema for definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a list of alerts with multiple events' with a specific verb and resource. It also distinguishes itself from the v2 sibling by explicitly labeling itself as a legacy endpoint and linking to the v2 alternative, removing any ambiguity about version differences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'This endpoint is legacy. Use the Get Alerts Multi-Events v2 endpoint,' providing an explicit alternative. It also gives context on result set limits and offset semantics, guiding when to use this endpoint for filtered/all results. It lacks explicit 'when-not-to-use' beyond the legacy warning but still offers clear direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 the required license, the HTTP endpoint, the ID limit (up to 20), and provides an example request body. 'Get' implies a read-only operation, and the example clarifies the input structure. However, it does not describe the response format or error behavior, which would be useful but is not critical given the clear 'Get' semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a short opening sentence, then license, endpoint, and example. It is front-loaded and efficient. The slight redundancy between the heading 'Get Internet Exposure' and the first sentence is minor, but overall it is concise and each section serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description is fairly complete for a single-parameter read tool. It covers licensing, endpoint, input structure, and ID limits. However, it does not describe what the response contains or any additional context like pagination or error cases, which leaves some ambiguity for agents expecting a full picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes 'asm_id_list' as asset IDs, but the description adds critical meaning: the limit 'up to 20 IDs' and a concrete example with a placeholder. This goes beyond the schema's basic description and helps the agent understand how to construct the request correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Get Internet exposure asset details according to the asset ID.' It also specifies the input scope (up to 20 IDs), which distinguishes it from similar asset tools. The verb 'Get' and resource 'Internet exposure asset details' are precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: provide asset IDs (up to 20) and require a specific license. However, it does not explicitly compare with sibling tools such as 'assets_get_assets_internet_exposure' or other asset-oriented tools, nor does it state when NOT to use this tool. It gives clear context but lacks explicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 explicitly states the maximum result limit of 500, the required license tiers, and provides the exact REST endpoint. It also shows a request example with filters. However, it does not disclose pagination handling, error cases, or response structure, so it is strong but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear title and one-sentence summary. It includes relevant details (max limit, license, endpoint, example) without excessive fluff. However, the license line is redundant and awkwardly phrased ('Cortex XSIAM Premium or Cortex XSIAM Enterprise, Cortex XSIAM Enterprise Plus or Cortex XSIAM Premium'), which detracts slightly from conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested request_data object with multiple sub-fields, and no output schema. The description provides an example and mentions max limit, but lacks an overview of pagination using search_from/search_to, the performance impact of vulnerability_test_results, or the shape of the response. The schema mitigates some gaps, but the description itself is not fully complete for an agent to confidently invoke the tool in varied scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has rich descriptions for nested fields like filters and sort, but the top-level request_data parameter has no description (schema description coverage 0%). The description provides an example request body that shows the filter structure, adding some meaning beyond the schema, but it does not explain sort, search_to/from, or vulnerability_test_results. The example partially compensates, but significant gaps remain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get a complete or filtered list of all your external services', which uses a specific verb (Get) and resource (external services). This differentiates it from siblings like assets_get_external_service (singular) and assets_get_external_website, as it targets the full collection. The addition of the endpoint path and license requirement further ties it to a specific asset management operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when you need to retrieve all external services, with optional filtering. It does not explicitly mention alternatives or when-not-to-use scenarios, but the example and wording imply its role as a listing endpoint. The license requirement is a useful prerequisite. It stops short of naming sibling tools or exclusions, so it does not earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It adds the permission requirement, HTTP endpoint, and an example request. However, it does not disclose whether deletion is permanent and irreversible, whether there are any safeguards or confirmations, or what the API returns upon success or failure. These are important unknowns for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a clear heading, a one-sentence summary, permission note, and a useful example. There is slight redundancy between the heading 'Delete BIOCs' and the summary 'Delete BIOCs selected by filter,' but the summary adds the filter detail. The structure is logical and each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a practical example and permission context, making it usable for straightforward calls. However, there is no output schema, and the description does not mention what the response contains, how success is indicated, or how edge cases (e.g., zero matching BIOCs) are handled. For a delete operation, these missing details leave the tool only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has detailed descriptions for the nested filter fields (field, operator, value) but the top-level request_data parameter has no description (0% schema description coverage). The tool description compensates by providing a concrete example request body that illustrates the structure and interplay of the filters. While it doesn't explain every parameter, the example adds significant semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('BIOCs'), and the selection mechanism ('selected by filter'). It also includes an example request body that reinforces the exact scope. This distinguishes it from sibling tools like bioc_insert and bioc_get through the explicit delete verb and filter-based selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool is for deleting BIOCs that match a filter, and it explicitly notes the required 'Instance Administrator' permission. While it doesn't name alternative tools or specify when not to use it, the filter-based deletion scenario is well implied and the permission prerequisite adds practical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the permission requirement and POST method, which is useful, but it doesn't describe response format, pagination, or error behavior. The 'get' wording implies read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is mostly front-loaded with a clear purpose, then adds permission, endpoint, and an example. It is slightly redundant with the 'Get dashboards' heading and the body, but the example is valuable and the length is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers input fields, permissions, endpoint, and provides an example, which is strong. However, with no output schema, it doesn't describe the response structure or how filters combine, leaving some gaps for a complete AI invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the signal indicates 0% schema description coverage, the actual schema includes detailed field/value/operator descriptions. The description adds a concrete example request body and explains the filtering fields, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get dashboard details' and specifies filtering by dashboard name, ID, time generated, or source. This distinguishes it from sibling tools like dashboards_insert and dashboards_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context including required Instance Administrator permission, the exact HTTP endpoint, and an example request body. It doesn't explicitly name alternatives or exclusions, but the usage context is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 discloses limits (100 max), filtering behavior (AND only), offset behavior, and license requirements, which adds value beyond the schema. However, it does not describe the return format or any authentication/rate-limit implications, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal but well-organized: summary, bullet points for constraints, license, endpoint, and example. Every section adds value, though the example JSON is somewhat verbose. Front-loaded with the core purpose, so the structure earns a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and one nested parameter, the description covers critical behavior (limits, filtering logic, license) and provides an example. However, it omits any description of the response shape or fields, which would be valuable given no output schema exists. This gap leaves it short of a 4, but it is not incomplete enough for a 2.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds meaningful semantic context beyond the schema: it explains AND vs OR behavior, explicit offset semantics, and provides a full example request body. This clarifies how parameters interact in practice, which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Gets'), the resource ('a list of device control violations'), and the filtering capability. It distinguishes itself from sibling tools by specifying 'device control violations' as the unique resource, which is not present in other get-type tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on usage: maximum 100 results, AND concatenation for multiple filters, zero-based offset semantics, and required license levels. It does not explicitly name alternative tools or when not to use it, hence not a 5, but the context sufficiently guides an agent on when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the required license (Cortex XSIAM Premium or Identity Threat Module) and the read-only nature via the verb 'Retrieve'. However, it does not mention potential side effects, rate limits, or pagination, though these may not be critical for a simple get operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured, with a title, one-sentence functional description, license requirement, and endpoint reference. Every part serves a purpose, with no unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameter-less tool, the description covers the purpose, license prerequisite, and expected output (list with reasons). It does not specify any limits or sorting, but this is not essential for a straightforward retrieval. The absence of an output schema is compensated by the clear description of results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to add parameter semantics, and it correctly focuses on the output and license requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a list of endpoints with the highest risk score in your environment along with the reason for each score.' This provides a specific verb (retrieve), resource (endpoints with highest risk score), and scope (your environment), distinguishing it from siblings like get_risky_users or get_risk_score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need endpoints with the highest risk scores, but it does not explicitly discuss when to use this tool versus alternatives such as get_risky_users. It does mention the required license, which is a prerequisite, but not comparative usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 a read-only operation ('Retrieve'), lists required licenses, and shows the HTTP endpoint. However, it does not mention error scenarios, pagination, or response format, and the POST method could be surprising for a retrieval operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core action in the first sentence followed by license and an illustrative example. Every sentence earns its place with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation, the description covers purpose, license, and request format. It lacks explicit return-value structure but states the output is user emails, which is sufficient for a simple tool. The absence of annotations and output schema is partially compensated by the clear description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive field names, so baseline is 3. The description adds a concrete example request body clarifying the nested structure of request_data and group_names, which goes beyond the schema's terse descriptions and aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool 'Retrieve a list of the current user emails associated with one or more user groups,' clearly identifying the action, resource, and output. It distinguishes from sibling tools like rbac_get_users and rbac_get_roles by focusing on group-based user email retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing user emails for specific groups but does not explicitly contrast with alternatives such as rbac_get_users or provide when-not-to-use guidance. The license requirement and endpoint are useful context but do not serve as usage exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral context. It discloses required license and the endpoint, but does not mention permissions beyond license, pagination, rate limits, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is compact and well-organized: title, one-sentence purpose, license, and endpoint. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list tool, the description adequately covers purpose, license, and endpoint. It lacks explicit mention of response format or pagination, but the simplicity of the operation reduces the need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so schema coverage is trivially 100%. The description adds no parameter detail because none exist, earning the baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve a list of the current users' with a specific verb and resource. It distinguishes from sibling tools like rbac_get_roles and rbac_get_user_group by focusing on users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned. License requirements are prerequisites but do not help choose between this and other RBAC tools. Usage is implied by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 required license, HTTP method, and endpoint management category, but does not detail side effects, reversibility, or response behavior beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, license requirements, endpoint path, and a concise example. Every sentence earns its place without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation endpoint with no output schema or annotations, the description provides license, API route, and a full request example. It stops short of describing the response format or error behavior, but the included details are sufficient for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides rich parameter descriptions (100% coverage), so baseline is 3. The example request body adds value by showing the context.lcaas_id field not present in the schema and illustrating the filters/tag structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line 'Remove one or more tags from one or more endpoints' uses a specific verb and resource, clearly stating the tool's function. This also distinguishes it from the sibling tool tags_agents_assign and other endpoint operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: use when removing tags from endpoints, and the description provides required licenses and an example request body. However, it does not explicitly contrast with tags_agents_assign or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are present, the description carries the full burden of behavior disclosure. It reveals key limitations (XQL only) and permission requirements. However, the example request uses 'name' instead of 'title', creating ambiguity about valid filter values and slightly undermining transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, a note, and a permission requirement. The example is somewhat long but illustrative. The text earns its place overall, though the example's length could be trimmed and the field-name error fixed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the endpoint, permission, XQL-only scope, and provides a request example. It does not explicitly state filter combination logic (AND/OR) or return format, but for a simple get-by-filter tool with a detailed schema, this is largely adequate. The field-name error is the main completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema itself provides rich descriptions for the filter fields and operators. The description adds a concrete example, but that example uses 'name' for the field, which contradicts the schema's 'title' enum. This misleading example reduces the value added beyond the schema and risks incorrect invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves widget details by filtering on widget title and creator. It also distinguishes the tool's scope by noting it only returns XQL widgets, not predefined widgets, setting it apart from widget insert/delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit when-not condition: it only returns XQL widgets, not predefined widgets. It also states the required Instance Administrator permission, which is critical usage guidance. However, it does not name specific alternative tools for predefined widgets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the operation type (insert/update) and the required 'Instance Administrator' permission, and provides an example body. However, it does not describe upsert semantics (whether existing widgets are overwritten or merged), side effects, or the response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The prose is concise: two sentences stating purpose and permission, plus the endpoint. The large example body is useful and directly illustrates the input structure, so it earns its place. It is appropriately front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the operation, permission, and provides a comprehensive example. However, it lacks information about the response format, error handling, and idempotency/upsert behavior. Given no output schema and no annotations, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, 'request_data', with no top-level description, but the description includes a detailed example request body showing the structure of request_data and widgets_data with concrete field values. This compensates for the schema's lack of descriptions, though it does not explicitly explain each field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert or update widgets' and elaborates with 'Update or add the widgets retrieved by the Get widgets API.' This specifies the action (insert/update) and resource (widgets), and distinguishes it from siblings like widgets_get (read) and widgets_delete (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool: for updating or adding widgets that came from the Get widgets API. It also mentions the required Instance Administrator permission, which adds decision-making context. However, it does not explicitly mention alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden of behavioral disclosure. It discloses a maximum result set size of 100, the required license, and that only PAN NGFW alert types are eligible. The word 'Retrieve' implies a read operation, and no contradictions are visible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a short summary, context, constraints, license, endpoint, and example. It is front-loaded and each section contributes useful information, though the example JSON adds length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a retrieval tool with no output schema, the description covers the essential context: what it returns, the related APIs, licensing prerequisite, result size cap, and an example request. It does not explain error handling or response structure, but those are not critical for selecting/invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides an example request body using filters, sort, search_from, and search_to, which illustrates valid values. However, it does not explain the semantics of these parameters, and schema description coverage is reported as 0%, leaving the agent to rely on the schema comments. This is partial compensation, not full.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Retrieve PCAP Packet' and then specifies exactly what is returned: 'a list of alert IDs and the associated PCAP triggering packets of PAN NGFW type alerts'. This is a specific verb+resource statement that distinguishes it from sibling alert tools like alerts_get_alerts, which do not fetch PCAP packets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context by stating these packets are 'returned when running the Get Alerts and Get Extra Incident Data APIs' and lists the required Cortex XSIAM license. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough for an agent to recognize this is for PCAP retrieval on PAN NGFW alerts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the API limit (20 IDs), the required license, and the POST method, which is helpful. However, it does not discuss response format, error behavior, or explicit read-only nature beyond the verb 'get'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a short summary, then the limit, license, endpoint, and example. Each part is purposeful, though the license line is somewhat verbose. Overall it is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description gives enough to invoke it correctly. It includes the request structure and constraints. However, it does not clarify the difference from the plural sibling 'assets_get_external_services' or describe the return payload, which would be valuable given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the parameters. The description adds value by clarifying the 20-ID limit and providing an example JSON body, which helps understand the nested request_data structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get service details') and the resource ('according to the service ID'), making it unambiguous. It also distinguishes from the sibling 'assets_get_external_services' by focusing on ID-based lookup and explicitly allowing up to 20 IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: the HTTP endpoint, required license, and an example request body. It does not explicitly mention alternatives or when-not-to-use, but the scope is well-defined enough to guide invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It discloses the mutation ("Create"), the authorization requirement (Instance Administrator), and the required input modes. It doesn't describe response shapes or side effects on existing authentication flows, but it provides far more behavioral context than a minimal description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description repeats the exact same sentence as both a title and the first paragraph, which is unnecessary redundancy. The example request body is large but useful for a nested structure. The overall structure is logical, but the duplication prevents a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex create tool with no annotations and no output schema, the description covers purpose, permissions, and input constraints well. However, it doesn't describe what the response/return value looks like or mention potential failure/error cases, leaving some uncertainty for an agent invoking the tool. This is a meaningful gap given the lack of structured output information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema's nested properties already describe most fields in detail, so the description only needs to add semantics beyond that. It does so by giving a complete example request body and, more importantly, stating the otherwise undocumented either/or constraint between metadata_url and the idp_sso_url/idp_issuer/idp_certificate group. This adds real value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource phrase: "Create authentication settings for IdP SSO or metadata URL." This clearly identifies the action and resource, and the "create" framing distinguishes it from the sibling tools authentication_settings_update, authentication_settings_delete, and authentication_settings_get_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: it states the required field combination (either metadata_url or all of idp_sso_url, idp_issuer, and idp_certificate) and the required Instance Administrator permission. It doesn't explicitly name alternatives like authentication_settings_update, but it's clear this tool is for creation, not modification, so the usage context is solid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 operation is destructive ('Delete all authentication settings'), requires specific permissions ('Instance Administrator'), and has a limitation (default config cannot be deleted). It does not mention irreversibility or error handling on default config attempts, but the core behavior is transparent for a delete endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses a structured format with title, note, permissions, endpoint, and example. Every sentence contributes value: the note explains the default configuration limitation, the permission line is essential for authorization, and the example illustrates the request body. It is slightly verbose with endpoint details but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool with no output schema, the description covers purpose, permission, limitations, and example. It does not explain what happens on success or if the default config is targeted, but those are not strictly required given the simplicity. The description is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a nested request_data object with a domain property, and the schema description for domain is present but context reports 0% coverage. The tool description compensates by explicitly stating the domain identifies which settings to delete and provides an example request body. However, the example uses 'str' as a placeholder and does not clarify domain format or constraints, so it only provides marginal additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Delete authentication settings by domain' and expands to 'Delete all authentication settings for the specified domain.' This provides a specific verb (delete), resource (authentication settings), and scope (by domain), which distinguishes it from sibling tools like authentication_settings_update or authentication_settings_get_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (when all settings for a domain need to be removed) and includes critical exclusions: the default configuration cannot be deleted, and Instance Administrator permissions are required. It does not explicitly mention alternatives (e.g., update instead of delete), but the context is clear and the constraints are meaningful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 the overwrite behavior based on rule_id, tenant-specific constraints, and permission requirements. It also provides the endpoint URL, but does not explain return values or error handling, which would be expected for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it opens with the purpose, then adds a critical note, permission requirement, endpoint, and a comprehensive example. Every section earns its place, and despite the length due to the example, it remains focused and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, lack of output schema, and absent annotations, the description covers the essential operational behavior (upsert, permissions, rule_id). However, it does not mention what the API returns on success or failure, nor does it explain required vs optional fields for insert vs update. This leaves some gaps for an agent to invoke correctly in all scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 explains the crucial rule_id behavior and provides a fully detailed example request body, which adds significant meaning beyond the schema. However, it does not describe each parameter individually, leaving some fields only illustrated in the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert or update BIOCs' and expands on the upsert semantics, distinguishing it from sibling tools like bioc_get and bioc_delete. The verb+resource pairing is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use (insert/update), notes tenant-specific rule_id behavior, and requires Instance Administrator permissions. It does not explicitly mention alternatives or when not to use, but the upsert semantics and permission note provide sufficient usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 explicitly states the overwrite behavior (same id on a tenant overwrites the existing rule), the tenant-specific nature of the id, and required permissions. It also includes the API endpoint, providing additional operational context beyond basic safety traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a bold statement, a note, permissions, endpoint info, and an example. The example is lengthy but serves as essential documentation for the nested request structure. Every section contributes to understanding, with no redundant fluff, earning a high but not perfect score due to its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core aspects: purpose, behavior, permissions, endpoint, and example payload. It does not explain the return value or error scenarios, but for an insert/update tool with no output schema, this is a minor gap. The example and caveats make it sufficiently complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema includes descriptions for many fields, and the description provides a comprehensive example request body that demonstrates typical values and relationships. However, the description itself does not explain individual parameters beyond the example, leaving some nuance to the schema. Since the schema coverage is incomplete for a few fields like 'dataset' and 'rule_id', the example partially compensates but does not fully replace per-parameter explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert or update Correlation Rules' and repeats the action with 'Insert new Correlation Rules or update existing Correlation Rules.' This identifies the specific verb (insert/update) and resource (Correlation Rules), and it is distinguishable from sibling tools like correlations_get and correlations_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (creating or updating correlation rules) and includes important caveats about tenant-specific IDs and required Instance Administrator permissions. It does not explicitly name alternative tools, but no other sibling tool provides this insert/update capability, so the guidance is effectively clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses license requirements and environment constraints, and implies a read-only retrieve operation, but does not detail response format, pagination, or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with the title followed by a one-sentence description and then important constraints. Minor redundancy exists between the title and first sentence, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless list operation, the description provides key contextual details: license requirements, environment, and what it returns. It lacks detail on output format but is sufficient for a straightforward retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description doesn't need to add parameter meaning. The baseline of 4 applies given zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of XQL user datasets created via the Cortex SDK, using a specific verb and resource. It distinguishes from sibling tools like xql_get_datasets by scoping to SDK-created datasets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for usage, including required license tiers and that it only works within the XSIAM Notebook environment. However, it does not mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses the destructive behavior: 'Running this API will delete all existing user names.' It also notes license requirements and the HTTP endpoint. It does not describe the response format or whether the action is reversible, but the key warning is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear short title, a concise explanation, a prominent warning, license info, endpoint, and an example. The example is lengthy but necessary to understand the nested structure. Every part contributes to the agent's ability to invoke the tool correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's nested schema and lack of output schema, the description is sufficiently complete for selection and invocation. It states the purpose, the destructive consequence, the license requirement, and the exact request format via example. It does not mention the return value, but that is not essential for this operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the top-level request_data, but the description provides a complete example request body with fields and comments. The schema already describes value and comment, so the example adds structural context rather than new semantics. The description does not explain why request_data is necessary or any constraints beyond what the schema shows, but the example compensates partially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Replace Featured Users' and 'Replace the featured users listed in your environment.' This clearly distinguishes it from sibling tools like featured_fields_replace_hosts or featured_fields_replace_ip_addresses by explicitly naming 'users' as the target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the purpose clear ('Replace the featured users listed in your environment') and adds critical context about the destructive action ('Running this API will delete all existing user names'), which implicitly warns against using it for incremental updates. It also specifies required licenses. It does not explicitly mention alternative tools, but none exist for the same resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It explicitly states the AND-condition only, zero-based offset, a maximum result set size (though phrased ambiguously as '>100'), and required permissions. It also gives the REST endpoint and an example request. However, it does not describe the response shape or error behavior, which keeps it from earning a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: a summary line, bullet points for key behaviors, UI navigation, permissions, endpoint, and an example. It is somewhat verbose with repeated phrasing ('Get Indicators' and 'Get a list of IOCs'), but each section serves a purpose and the example is practical. Overall, it is concise relative to the amount of useful information present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description addresses filtering semantics, pagination, authentication, and endpoint location. It also includes a concrete example. However, it leaves the maximum result set size ambiguous ('>100') and does not explain what the response includes beyond 'all details' when extended_view is true. Since there is no output schema, this omission is noticeable but not fatal given the other covered aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already includes rich descriptions for all parameters (fields, values, operators, pagination). The tool description adds an example request body that illustrates how to structure filters and extended_view, which is helpful but does not deeply elaborate on each parameter. Since schema coverage is effectively comprehensive, the description's additional semantic value is marginal, meriting a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Indicators (IOCs)' and 'Get a list of IOCs', clearly identifying the specific action (list/retrieve) and resource (IOCs). It distinguishes from sibling tools like indicators_insert and indicators_delete by focusing on the read operation. The mention of filtering and extended results adds further specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context: it explains that results can be all IOCs or filtered, notes AND-condition concatenation (OR unsupported), and describes offset behavior. It also mentions required Instance Administrator permissions and gives a UI navigation path. It does not explicitly compare to alternatives, but sibling tools are clearly distinct actions (insert/delete), so the guidance is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It states required permissions, the filter mechanism, and that an empty request_data deletes all syslog servers. It does not explicitly mention irreversibility, but the destructive nature is clear from 'Delete all' and the operation name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief summary, permissions note, endpoint reference, and a concrete example. Each section serves a purpose and there is no filler. The code block is appropriately formatted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with one nested parameter, the description covers deletion scope, filtering, permissions, and provides an example. It does not describe response format or error conditions, but these are less critical for a simple delete endpoint. The minor operator-case inconsistency is a slight flaw.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage, so the baseline is 3. However, the example request body uses 'operator': 'EQ' (uppercase) while the schema enum is 'eq' (lowercase). This misleading example could cause an agent to send an invalid value, actively undermining the schema's clarity. The description adds confusion rather than value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete all or filtered syslog integrations', a specific verb-resource pair that clearly states the action and scope. It distinguishes this tool from siblings like integrations_syslog_create/get/update/test by focusing solely on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool's capability to delete all or filtered integrations, and includes the required permission ('View/Edit Alert Notification'). However, it does not explicitly name alternatives or exclusion scenarios, though sibling tool names imply the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It reveals that the result is a ZIP file containing YAML, requests a POST endpoint, and states the required admin permission. It omits error behavior or what happens when no script matches, but for a read-only fetch, this is reasonable coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a short intro, permission note, endpoint reference, and example. It is not excessively verbose, and each section contributes useful information. The example is slightly long but valuable despite the typo, so it earns a 4 rather than 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 output schema, no annotations—the description covers the essential context: what it returns, how to filter, and the required permission. It lacks explicit comparison with sibling tools and error handling, but those are not critical for a straightforward retrieval operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds an example request body and states that filters can be based on name or ID, which helps interpret the schema. However, the example uses 'filters' while the schema defines 'filter', creating a mismatch that could mislead an agent. Schema description coverage is 0%, so the description should compensate, but it only partially does—the typo is a notable flaw.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Get' and the resource 'script', and clarifies the retrieval mechanism ('by filtering based on its name or ID') along with the output format ('YAML is returned in a ZIP file'). This distinguishes it from sibling tools like scripts_get_script_metadata and scripts_get_script_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: you need to know the script's name or ID and must have Instance Administrator permissions. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5, but it gives sufficient guidance for selecting this tool over generic getters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 mutation nature (insert/update), the permission requirement, and the input format (YAML in a ZIP). However, it omits behavioral details such as whether an existing script is overwritten, idempotency, or the return response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with purpose, and every sentence adds value: purpose, input format, permission, and endpoint. No wasteful repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the essentials (purpose, permission, input format) but lacks operational details needed to invoke correctly, such as how to pass the ZIP (multipart, base64), what fields are expected, or any request structure. Given the empty schema and no output schema, the description is not fully complete for an agent to make the call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with additionalProperties true, so the baseline is 4. The description adds meaning by specifying the key input: 'YAML in a ZIP file.' It does not provide parameter names or structure, but it gives the essential information about the payload.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert or update a script' with a specific verb and resource. It distinguishes itself from sibling script tools like scripts_run_script, scripts_get_scripts, and scripts_delete by focusing on creation/update via YAML in a ZIP file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use it (adding/updating scripts) and notes the required Instance Administrator permissions. It does not explicitly name alternatives or exclusions, but the context makes the use case clear relative to running, fetching, or deleting scripts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 discloses the 1000-result maximum, lack of pagination, and the existence of a streaming alternative, plus license requirements. However, it does not mention non-destructive read-only semantics, potential PENDING status returns, or error behavior, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement, informative notes, a link for further reading, license info, endpoint, and an example. It is slightly verbose but every section contributes useful context, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description covers the key operational constraints (result size, stream alternative, license), and provides an example. It does not explain return statuses or how to handle PENDING, but the schema covers pending_flag semantics, so the overall context is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides an example request body illustrating the nested request_data structure with query_id, pending_flag, limit, and format. The input schema already has detailed descriptions for these nested properties, so the description adds marginal semantic value beyond the schema, mostly clarifying structure via the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get XQL query results' and 'Retrieve results of an executed XQL query API', using a specific verb and resource. It distinguishes from sibling tools by noting that it only works with queries initiated by start_xql_query and that results over 1000 require the Stream API.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: it only works with XQL queries from start_xql_query, and explicitly directs users to Get XQL query results Stream for responses over 1000 results. Also mentions parallel query quota limits, giving practical usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and discloses several behavioral traits: chunked transfer encoding, optional gzip via Accept-Encoding header, the four-parallel-query quota, and required license tiers. It stops short of explaining error behavior or stream consumption details, so it is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for the overview, notes, license, endpoint, and example, with the key purpose front-loaded. It is somewhat long but most content is relevant; the slight redundancy between the gzip header instruction and the example's is_gzip_compressed field is minor.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the endpoint path, example request, license, prerequisite, quota, and response encoding, providing solid invocation context. It lacks an output schema and does not describe the exact response body structure beyond chunked/gzip, so the stream format remains only partially specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The example JSON body shows the nested request_data with stream_id and is_gzip_compressed, which helps structure. However, the meaning of is_gzip_compressed remains ambiguous because the description instructs using the Accept-Encoding header for gzip but does not clarify the field's role. The schema only says 'A boolean flag,' so neither source fully explains it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool retrieves XQL query results as a stream for result sets larger than 1000 results. It also notes the endpoint only works with queries initiated by start_xql_query, which distinguishes it from xql_get_query_results and xql_query in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions the >1000-result use case and the prerequisite that the query must originate from start_xql_query, and provides quota guidance. It does not explicitly name the alternative for <=1000 results, but the threshold strongly implies when to use this stream endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It discloses the permission requirement and warns about unique query names, but does not explain the behavior when xql_queries_override is false or whether the operation returns a specific response. The override behavior is only spelled out in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: a clear summary, then a usage note, permission requirement, endpoint reference, and an illustrative example. Every section adds value, and the example is concise despite being detailed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description could be more complete. It covers the core functionality, permissions, and an example, but omits any mention of return values, error handling (e.g., when override is false and a query exists), or pagination/conflicts. The duplicate xql_query_name in the example may also confuse agents trying to infer uniqueness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has low description coverage (0%), but the description includes a complete example request body that clarifies the structure of request_data and its nested fields (xql_query, xql_query_name, xql_query_tags, xql_queries_override). This adds practical meaning beyond the bare schema, helping the agent construct a valid request.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Insert or update XQL queries', clearly stating the action (insert/update) and resource (XQL queries). This distinguishes it from sibling tools like xql_library_get and xql_library_delete, leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to insert new or update existing XQL queries. It also includes a practical prerequisite (Instance Administrator permissions) and a uniqueness note, though it doesn't explicitly reference alternatives or exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It discloses concurrency limitations, all-or-nothing deletion behavior, AND matching semantics, timeout, and required licenses. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose but well-structured with headers, notes, and bold text. The first two sentences are slightly redundant, but the additional behavioral warnings are valuable and justify the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key aspects of a complex delete operation: concurrency, atomicity, matching logic, timeout, and licensing. However, it omits return value details and error handling, and the 'filter blocks' ambiguity leaves some structural gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the top-level parameter, and the description does not compensate. It uses ambiguous terms like 'filter blocks' that may not align with the schema's single 'filters' object, and it does not explicitly name or explain the 'request_data' structure beyond vague references to 'specified parameters'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove data from a lookup dataset' with a specific verb and resource. It distinguishes from sibling tools like xql_lookups_add_data and xql_lookups_get_data by focusing on removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (removing data based on filters) and includes important behavioral constraints like concurrency and all-or-nothing semantics. It does not explicitly mention alternatives or exclusions, but the context is sufficient for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses important behavioral constraints: rate limit, required role ('App Service Account'), required licenses, and field-naming conventions. It does not mention response format or error behavior, but provides substantial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, but opens with a redundant title repetition ('Create a Custom Alert' then 'Create a custom alert'). Overall it is appropriately sized and front-loaded, with most sentences providing necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, but the description covers mandatory fields, optional fields, naming conventions, rate limits, roles, and licenses. It lacks response format and error-handling details, which are significant for an API call, but given the complexity, the description is quite thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
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 this excellently by explaining mandatory fields, naming conversion rules (lower camel case, hyphen-to-underscore), and listing recommended fields with concrete examples (e.g., 'Container ID' -> 'container_id'). This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a Custom Alert' with mandatory fields. It is specific about the resource and action, but doesn't distinguish from sibling tools like alerts_insert_cef_alerts or alerts_insert_parsed_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context including mandatory fields, recommended fields, rate limit ('up to 600 alerts per minute'), and required role/license. However, it does not explicitly mention when to use this tool versus other alert-insertion sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 discloses the batch limit, 'missing fields are ignored', and required license, which adds valuable context. However, it does not describe response format, error behavior, or reversibility, leaving some gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: a brief summary, batch limit, missing-fields behavior, license requirements, endpoint, and a concrete example. Every section serves a functional purpose with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers request formation with an example, batch limits, partial update semantics, and licensing, which is substantial for a tool with nested objects. However, it lacks return value or error information, and the requirement for alert_id_list is only implied by the example, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by providing an example request body that shows the exact nesting (request_data, alert_id_list, update_data) and by clarifying that missing fields in update_data are ignored. This adds practical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update one or more alerts' with a specific verb and resource, and adds useful constraints (up to 100 alerts, missing fields ignored). This distinguishes it from siblings like incidents_update_incident (different resource) and alerts_create_alert (create vs update).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool to update alerts in batches, with explicit limits and partial update behavior. It does not explicitly name alternatives or exclusions, but the resource and operation are unambiguous, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 the output semantics ('A status of "true" indicates the websites data update was successful') and identifies the HTTP method and endpoint. It doesn't cover edge cases or authorization, but for a read-only query 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with a title-like phrase, followed by a concise explanation and endpoint. No redundant information or fluff; every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 no output schema, the description provides enough context: it states the returned information (time and status) and the meaning of status. It lacks a detailed return format, but given the simplicity, this is a minor gap. The endpoint and domain ('Asset management') add useful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the schema's description for 'request_data' already states it takes an empty dictionary to return the assessment. The tool description adds no additional parameter meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Gets the time and status of the last update of websites data in Cortex.' It uses a specific verb ('gets') and resource ('last assessment of websites'), and the endpoint reference further distinguishes it from siblings like 'assets_get_external_websites' which likely retrieve the full list of websites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on what the tool does (checking the last assessment status), which implies when to use it. However, it doesn't explicitly mention alternatives or exclusions, so it falls short of a 5. The context is sufficient for an agent to infer its purpose relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses required licenses and the consequence that new agents (including VDI) cannot register after deletion. However, it does not explicitly state whether deletion is permanent/irreversible or what happens to existing agents, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and each section earns its place: purpose, parameter sourcing, behavioral note, license, and example. It is slightly verbose with blank lines but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive action with one parameter, the description provides enough context: usage, effect, license, example, and endpoint. It does not cover error conditions or output, but with no output schema and a simple action, the missing pieces are acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given the context signal of 0% schema description coverage, the description fully compensates. It explains that distribution_id is required, where to find it (Create distributions API response or Agent Installations screen), and provides an explicit example request body, adding meaning beyond the schema's minimal 'Installation package distribution ID.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Delete agent installation packages' – a specific verb and resource. It clearly distinguishes from sibling distribution tools (create, get_versions, get_status, etc.) by indicating this is the deletion operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context: it's used to delete a distribution, with a note about the effect on new agents. However, it does not explicitly mention when not to use it or alternative tools (e.g., distributions_create to make a new package), stopping short of the 'explicit when/when-not/alternatives' bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 required license and the exact endpoint (POST /public_api/v1/distributions/get_versions), adding behavioral context. However, it does not explicitly state whether the operation is read-only or describe the response format, leaving some behavioral traits undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a two-sentence title and detail, with the endpoint and license inline. No redundant words or over-specification. The structure front-loads the purpose and adds supporting details efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description covers the core purpose, license requirements, and endpoint. It stops short of declaring read-only behavior and return structure, but given the tool's simplicity, the provided context is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero defined parameters (with additionalProperties true), so the baseline per rules is 4. The description correctly avoids inventing parameter details, and the empty schema leaves nothing to explain. The additionalProperties true is not addressed, but with 0 params this is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Distribution version' and expands to 'Get a list of all the agent versions to use for creating a distribution list,' specifying both the verb and the resource. It distinguishes from sibling distribution tools like distributions_create, distributions_delete, distributions_get_status, and distributions_get_dist_url.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage context by saying 'to use for creating a distribution list' and lists required license levels, indicating when this tool is appropriate. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 HTTP method and path, required license, parameter constraints, and an example request. It also notes the error condition when both endpoint_id and filters are used. It does not describe the response format, but the behavior is mostly clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise summary, a usage note, license requirement, endpoint path, and a concrete example. Every sentence adds useful information and the layout makes it scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with nested schema and no output schema, the description covers the core operation, parameter constraints, license, and an example. It lacks details on response payloads or other error cases, but the provided information is sufficient for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value with an explicit example request body, the mutual-exclusivity error condition, and clarification that incident_id affects the timeline display. These enrich the schema details without being redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reverse the isolation of one or more endpoints') with a specific verb and resource, distinguishing it from the sibling tool endpoints_isolate. It also clarifies that a single request can handle multiple endpoints, adding scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides internal usage guidance about mutually exclusive parameters (endpoint_id vs filters) and the required license, but it does not explicitly contrast this tool with alternatives like endpoints_isolate or endpoints_restore. The 'when to use' is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 discloses that the response depends on the entry type and that filters apply, and it provides an example request. However, it does not mention pagination specifics, authentication, or error behavior, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear lead sentence, an example, and categorized filter details. However, it repeats 'Get War Room entries' twice in the opening, which is slightly redundant. Still, every other part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, and the description does not explain response formats beyond noting that the response depends on the entry type. The example only covers the request body, not the response structure. Given the tool's complexity, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes parameters, and the description adds an example request body showing usage of `id` and `filter` with nested fields. It also mentions filtering by timestamp, ID, and tags, helping the agent map abstract concepts to actual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get War Room entries' for a specific incident or alert, with filtering options and entry type selection. This distinguishes it from sibling tools like incidents_get_incidents and alerts_get_alerts by focusing on War Room entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool (for a specific incident or alert) and describes filtering and entry type selection. However, it does not explicitly mention when not to use it or name alternative tools, so it lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses an important behavioral constraint (does not create War Rooms) and gives the HTTP method, but does not mention permissions, failure modes, or response behavior. This is a moderate transparency level for a simple insert operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the purpose. The note, endpoint, and example are each useful and not redundant, providing essential operational detail without unnecessary padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers the key context: endpoint, prerequisite, and example usage. The absence of an output schema is partially mitigated by the straightforward nature of an 'insert' operation, though return-value details are not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for both parameters, so the baseline is 3. The description adds a concrete example showing how to pass a command as 'data', which clarifies real-world usage beyond the schema. The minor inconsistency in example casing ('Id' vs 'id') is a slight flaw.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear action verb and target resource ('Add War Room entries'), and further specifies it applies to incident or alert War Rooms. This clearly distinguishes it from read-only siblings like entries_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The note clearly states a critical precondition: the War Room must already exist and the endpoint does not create one. It also implies the appropriate context (adding entries) without explicitly naming alternatives, but the distinction from retrieval tools is straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly warns about the destructive nature ('Running this API will delete all existing host names') and specifies the required license. It lacks details on response format or other side effects, but covers the most critical behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: title, purpose, warning, license, endpoint, and example. Each sentence adds value, and the example is useful. It is slightly long but not verbose, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, destructive behavior, and an example. However, it lacks any mention of the response/return value, sync/async execution, or error scenarios. With no output schema, the description should explain what happens after the call, which is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 provides an example request body showing the 'fields' array with 'value' and 'comment' objects, which clarifies the structure. It does not fully explain each parameter beyond what the schema already states, but the example adds practical meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Replace Featured Hosts' and 'Replace the featured hosts listed in your environment.' This uses a specific verb and resource, and the resource type (hosts) distinguishes it from sibling tools like featured_fields_replace_ip_addresses or featured_fields_replace_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context that this replaces the entire set of featured hosts, with a critical note that it deletes all existing host names. However, it does not explicitly compare to alternative tools or state when not to use this operation, which would elevate it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 explicitly warns that running the API deletes all existing IP addresses, which is crucial destructive behavior, and it lists required licenses. It does not describe return values or error behavior, a minor gap given the strong warning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: a clear purpose sentence, a prominent destructive warning, license requirements, endpoint path, and a representative example. Every element contributes value without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no output schema, the description provides purpose, the deletion warning, licensing, and a request example. It does not explain the response format or error scenarios, so it is not a 5, but it covers the most critical operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description itself has no parameter doc coverage (0%), but the example request body effectively illustrates the nested structure and accepted formats (single IP, range, CIDR). The input schema already defines 'value' and 'comment', so the description adds a concrete template but not much new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Replace' and the resource 'featured IP addresses' in the context of the environment. It is unambiguous and differentiates from sibling tools like replace_hosts, replace_users, etc., by specifically targeting IP addresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates this is for replacing featured IP addresses and includes a critical warning that all existing IP addresses will be deleted. It does not mention when to use this instead of the sibling replace tools, but the context is clear enough that an agent would know when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 adds valuable nuances: 'Missing fields are ignored', validation of assigned_user_mail, and special values ('none' or empty string) for unassignment and severity clearing. This goes beyond the basic 'Update' verb, though it omits auth requirements, response format, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a brief opening sentence followed by bullet-point notes. It front-loads the core purpose and keeps critical usage tips compact. The HTTP endpoint and context line are minimal and non-redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with a nested schema and no output schema, the description provides essential behavioral notes (ignored fields, unassignment, severity removal) that are not obvious from the schema. It lacks response format or error handling, but the schema's detailed property descriptions compensate, making the overall specification fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% per context, so the description must compensate for parameter meaning. It does add guidance for assigned_user_mail and manual_severity (using 'none' or empty strings), which is not in the schema. However, it does not explain other parameters like status, comment, or notes, leaving gaps that the schema descriptions partially fill.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('an Incident'), with a specific scope: 'Update one or more fields of a specific incident.' This distinguishes it from sibling tools like incidents_get_incidents or incidents_get_incident_extra_data, which focus on reading rather than modifying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to use the tool, including that missing fields are ignored, how to unassign an incident, and how to remove a manual severity. However, it does not explicitly state when to prefer this tool over alternatives or provide exclusions, though the context is sufficient for most use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure. It adds the permission requirement and the input format (YAML in a ZIP file), which is useful. However, it does not disclose side effects, idempotency, or response behavior, leaving some gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loads the primary purpose, and includes necessary contextual details (permissions and endpoint). Every sentence contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema), the description covers the essential aspects: purpose, input format, permission requirement, and endpoint. It does not mention response behavior, but this is not critical for a simple insertion tool with no output schema. The context is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with additionalProperties set to true, so there are zero defined parameters. The baseline for 0 params is 4. The description adds meaningful semantics by specifying 'passing the YAML in a ZIP file,' which indicates the payload format. This goes beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert or update playbooks' and elaborates with 'Add or update a playbook by passing the YAML in a ZIP file.' This provides a specific verb, resource, and input format, distinguishing it from sibling tools like playbooks_get and playbooks_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'Add or update a playbook by passing the YAML in a ZIP file.' It also states a required prerequisite: 'You must have Instance Administrator permissions to run this endpoint.' It does not explicitly mention alternatives or exclusions, but the context is clear enough relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 reveals the end-to-end polling behavior, the exit condition (max_wait_seconds returns pending status), and that it wraps two other calls. It would be stronger with details on error handling or the structure of the returned results, but the core behavior is well explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the core purpose, followed by a useful wrapper explanation and a concrete example. Every sentence earns its place; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description explains the return behavior (results or pending status) but not the exact structure. The schema covers all parameters, and the description adds the polling/timeout context. It could mention streaming as an alternative, but for an ad-hoc query tool, the information provided is sufficient to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters well. The description adds a full JSON example with 'query' and 'time_frame', which is helpful but largely redundant with the schema's own example for time_frame. There is no new parameter-level guidance beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs an XQL query end-to-end, starting the query, polling, and returning results. It explicitly names the wrapped operations (xql/start_xql_query + xql/get_query_results), distinguishing it from the sibling tools xql_start_xql_query and xql_get_query_results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'Prefer this for ad-hoc data investigation' and explains it saves manual polling. However, it does not explicitly mention when not to use it (e.g., for streaming results with xql_get_query_results_stream) or provide exclusion criteria beyond this preference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses important behavioral traits such as AND-only filtering, max result size, offset semantics, and PCAP indication. It does not discuss error handling or side effects, but for a read-only list operation 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a short intro followed by bullet points, a PCAP note, license info, endpoint, and a JSON example. It is slightly longer than necessary but every section contributes useful information. Purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested schema and no output schema, the description provides key contextual details: list of alerts, PCAP indication, max size, offset, and an example request. It does not enumerate alert fields, but that is not essential for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 not explicitly describe parameters, but it provides a detailed example request body that illustrates how to structure filters, search_from, search_to, and sort. The input schema itself contains rich descriptions, so the example adds practical value but does not fully substitute for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves all or filtered alerts with a specific verb ('Get a list of all or filtered alerts'). It distinguishes itself from the sibling tool alerts_get_alerts_pcap by noting that PCAP data should be retrieved via the Retrieve PCAP Packet API. The scope and resource are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage constraints: AND-only concatenation, maximum result set size of 100, zero-based offset, and license requirements. It also names an alternative (Retrieve PCAP Packet API) for PCAP-specific needs, giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of transparency. It adds valuable behavioral context: the operation is a write (upload), it has limits (500 items), it requires specific permissions and licensing, and it provides the exact API endpoint. It does not discuss error handling or idempotency, but it is quite transparent for the intended use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, details, permissions, license, endpoint, and example. It is slightly long but every part serves a purpose (limits, permissions, example). It avoids fluff and is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex nested request_data object, no output schema, and no annotations. The description adequately covers the input format, applicable limitations, and prerequisites. It does not describe the response/return value, which would be useful, but the provided information is sufficient for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds a concrete example request body showing how request_data is structured, including the exact format for ip_range asset identifiers and business_units. This example clarifies parameter usage beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Upload assets to the inventory' and specifies exactly what it uploads (domains, subdomains, IPv4 address ranges). It differentiates from sibling tools like asm_management_remove_asm_data (removal) and assets_get_external_* (read-only retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it explains what asset types are accepted, the maximum batch size (500), required permissions (Instance Administrator), and required licenses. It does not explicitly name alternative tools, but the purpose and constraints make when-to-use obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the maximum result limit, required license tiers, the HTTP endpoint, and includes an example request. These add substantial behavioral context, though it stops short of detailing response structure or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every part serves a purpose: clear opening, explicit limit, license requirement, endpoint, and example. No filler. The example is necessary to illustrate the complex filter structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested filters, sort), the description covers the key operational aspects: the action, filters, limit, and license. Without an output schema, it doesn't detail the response fields, but for a 'get' operation this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of parameter descriptions, but the description adds a concrete example body demonstrating how to structure filters, sort, and offsets. This goes beyond the schema and clarifies usage patterns for the nested objects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get all Internet Exposures', a specific verb+resource that clearly distinguishes this from sibling asset tools (e.g., 'assets_get_external_service', 'assets_get_asset_internet_exposure'). It further lists the filterable fields, leaving no ambiguity about the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that you can retrieve 'all or filtered results' and notes the 500-asset maximum limit, providing clear context. However, it does not explicitly name when to use this tool over alternatives or state exclusions, so it stops short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 reveals key behaviors: license requirements (Cortex XSIAM Premium/Enterprise/Enterprise Plus), status constraints, AND filtering semantics, and offset behavior. It does not mention potential side effects or the response format, but it covers the most critical behavioral aspects for invoking the tool correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose first, then usage condition, filtering notes, license, endpoint, and an example. It is slightly long due to the example JSON, but every part contributes useful information. The front-loaded purpose and concise explanatory paragraphs make it efficient despite the example length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested filters with multiple fields) and the absence of an output schema, the description covers the essential context for correct invocation: status constraints, filtering logic, license, and an example. It does not describe the response body or error cases, but the request semantics are thoroughly explained, making it almost complete for an action tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of parameter descriptions, including valid fields, operators, and value formats. The description adds value beyond the schema by clarifying the abort condition (pending/in_progress), explaining AND/offset behavior, and providing a full example request body. This enriches understanding without needing to reiterate schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: "Cancel the scan of selected endpoints." This distinguishes it from sibling tools like endpoints_scan (which would start a scan) and endpoints_quarantine (a different action). The title "Cancel Scan Endpoints" reinforces the purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage condition: "A scan can only be aborted if the selected endpoints are in **Pending** or in **Progress** status." It also explains filtering behavior (AND concatenation, zero-based offset). However, it does not explicitly name alternatives or state when not to use this tool, though the sibling endpoints_scan implies the opposite use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly discloses the destructive behavior ('delete all existing active directory groups') and the required license, which are critical for an agent to safely invoke the tool. It doesn't detail response format, but the core risks are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear summary, a warning note, license info, endpoint URL, and an example. Each section adds useful context without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers the essential operational aspects: what it does, the destructive side effect, license requirements, and an example. It is complete enough for an agent to understand the tool's purpose and risk profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema itself has rich descriptions for each field, the description adds an example request body that illustrates the exact structure and usage of the nested fields. This provides practical meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Replace') and a specific resource ('featured active directory groups and organizational units'). It clearly distinguishes from sibling tools like featured_fields_replace_hosts and featured_fields_replace_users, which target 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by specifying the resource type and including a prominent deletion warning. It does not explicitly name alternatives, but the context makes it obvious when to use this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a rate limit of 10 API requests per minute, required license tiers, the POST endpoint, and a PCAP-related response behavior. These operational details go beyond the schema and help the agent anticipate constraints, though the full response format is not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and succinct: a one-sentence summary, a note on PCAP, rate limit, license, endpoint, and a JSON example. No sentence is wasted; the structure front-loads the core purpose and supports it with necessary operational details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The request side is well covered, but with no output schema and no annotations, the response side is under-specified. It mentions 'extra data fields including alerts and key artifacts' and the PCAP condition, but does not describe the actual response structure, key artifact types, pagination, or error behavior, leaving meaningful gaps for an agent consuming the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds an example request body showing the nested 'request_data' structure with 'incident_id' and 'alerts_limit', which clarifies how to invoke the tool beyond schema field descriptions alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'Get extra data fields of a specific incident including alerts and key artifacts,' clearly stating the resource (incident extra data), the scope (specific incident), and the contents (alerts, key artifacts). This differentiates it from siblings like incidents_get_incidents (basic incident data) and alerts_get_alerts (alert retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need extra incident data and explicitly directs use of the 'Retrieve PCAP Packet' API for PCAP data, providing an alternative. It also notes the rate limit and required licenses, which help an agent decide when invocation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses important behavioral traits: response concatenation uses AND, max result set size is >100, offset is zero-based, and required licenses are specified. It also includes an example request. It does not explicitly state that the operation is read-only, but 'Get Incidents' strongly implies non-mutating behavior, and no side effects are mentioned. This is solid coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized but well-structured with bullets and an example. Every sentence adds information: filter capabilities, AND condition, result size, offset semantics, license requirements, and a worked example. While slightly longer than necessary, the complexity of the tool justifies its length. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has nested object parameters and no output schema. The description is complete enough for practical use: it explains filtering, sorting via example, result size limits, and licensing. It lacks details on return value structure, but since no output schema exists, that is not required by the rubric. It covers the main operational aspects an agent needs to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage, so the baseline is 3. The description adds practical semantics beyond the schema: it explains the AND condition, the all-or-filtered behavior, and gives a concrete example request body showing how to structure filters and sort. This helps an agent understand how to combine parameters correctly, which is valuable despite the schema being complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a list of incidents filtered by a list of incident IDs, modification time, or creation time.' It also clarifies scope (all incident types and severities, including correlation-generated incidents), which distinguishes it from sibling tools like incidents_get_incident_extra_data. The verb 'Get' and resource 'incidents' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it explains the AND condition, maximum result set size, offset behavior, and the ability to retrieve all or filtered results. It does not explicitly name alternative tools or state when not to use this tool, but the guidance is sufficient for an agent to decide to invoke it for listing incidents. The example request body further clarifies invocation details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 a critical limitation ('Cortex XDR does not scan historic data, but rather only new incoming data'), required licenses, and the endpoint. It does not detail side effects like overwriting, but insertion is reasonably clear. The validate parameter is mentioned as a way to see errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but efficiently structured: title, action, note, license, endpoint, and example. Every section contributes value, and the example is essential. It is not overly verbose despite the amount of context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a CSV upload tool with no output schema, the description provides a comprehensive example, license requirements, a behavioral limitation, and the endpoint. It could be more complete by specifying the response format, but the schema and example cover most needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds a concrete example request body demonstrating the exact CSV format, which is practical and goes beyond the schema's table. This helps the agent construct the request_data correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Insert'), resource ('Simple Indicators'), and format ('CSV'). It distinguishes itself from sibling tools by explicitly naming the CSV format, which sets it apart from indicators_insert_jsons and indicators_insert.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'Upload IOCs in CSV format that you retrieved from external threat intelligence sources.' It also includes an important caveat about historic data not being scanned and license requirements. However, it does not explicitly mention alternatives or when not to use this tool, though the format is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 pagination limits, offset semantics, AND-only filter behavior, optional all/filtered retrieval, license requirements, and PCAP-related response details. However, it does not describe the full return object structure or explicitly state that this is a read-only operation, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and uses bullets for constraints, followed by license, endpoint, and an example body. It is somewhat long but each section adds useful information; minor redundancy exists in repeating the tool name, but overall it is well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read/list tool with no output schema, the description covers purpose, filtering behavior, pagination, example request, and license requirements. It is operationally usable, though it lacks explicit sibling-tool guidance and a thorough description of the response payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage, so the baseline is 3. The description adds value by providing a concrete example request body and clarifying that multiple filters are combined using AND, with OR unsupported, which enriches the meaning of the filters parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get a list of alerts with multiple events,' which states a specific verb and resource. The title and endpoint ('v2') further distinguish this from sibling tools like v1_alerts_get_alerts_multi_events and alerts_get_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: AND-only filter combination, maximum result size of 100, zero-based offset, ability to retrieve all or filtered results, and required licenses. It does not explicitly name alternatives or state when not to use this tool, but the constraints are operationally actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 discloses concurrency limitations (no concurrent edits, data may be overwritten/deleted), a rate assumption (1000 entries per 10 seconds), a 50 MB size limit, a three-minute timeout, and the behavior of unspecified fields being set to None. This goes far beyond a basic add/update statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and structured with paragraphs and bullet points, making it readable. It repeats the first line, and the length is notable but each additional detail (concurrency, rate, size limit, timeout, license) is essential. The minor redundancy prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description covers critical operational constraints: size limit, timeout, concurrency, rate, and license. It does not describe the request payload structure or response, but the schema provides the structure, and the description focuses on behavioral context that is otherwise missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description elaborates on the `data` field and `key_fields` behavior (e.g., unspecified fields set to None, key_fields trigger updates vs inserts), which adds meaning beyond the schema. However, it does not mention the `dataset_name` parameter or the top-level `request_data` wrapper, leaving gaps for a complete understanding of the request structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Add or update data in a lookup dataset', clearly distinguishing it from sibling tools like xql_lookups_remove_data and xql_lookups_get_data. The action is unambiguous and the scope is defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on how to use the tool, explaining the behavior of key_fields for updates vs inserts and noting the license requirements. It does not explicitly mention alternative tools, but the guidance on when data is updated vs appended is actionable and context-rich.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It adds meaningful operational details: rate limits, request size caps, required Cortex XSIAM licenses, and that only successfully parsed alerts are displayed. It does not cover error responses or authentication, but the provided context is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: purpose, limits, license, endpoint, and example body. Every sentence contributes necessary information, and the example is long but justified by the nested schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex nested-input tool with no annotations and no output schema, the description covers the essentials: endpoint, rate limits, license, request structure via example, and expected display behavior. It lacks explicit return/error semantics, but is sufficiently complete for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description compensates with a complete example request body showing all fields (product, vendor, IPs, ports, event_timestamp, severity, etc.). This gives practical meaning to the nested request_data parameter, though it does not explicitly define field formats or requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Upload alerts from external alert sources in Cortex XSIAM format.' It uses a specific verb and resource, and distinguishes itself from siblings like alerts_insert_cef_alerts by specifying the XSIAM format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it is for external alerts in XSIAM format, includes rate limits (600 per minute, 60 per request), and lists required licenses. However, it does not explicitly mention when not to use it or name alternatives, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 asynchronous removal (within 24 hours), cascading deletion of related items (incidents, alerts, services, subdomains, IPs), required role/license, and a specific limitation. This goes beyond typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, but longer than necessary due to multiple caveats. Every sentence provides useful context, so the length is justified. Could be slightly more compact without losing important details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex removal tool with no output schema, the description covers the full lifecycle: what gets removed, limits, timing, side effects, prerequisites, and an example. This is exceptionally complete and leaves little ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the description doesn't need to compensate. The example request body is helpful, but the tool description adds no new parameter semantics beyond what the schema already provides. The schema itself contains a minor error ('add' instead of 'remove') but that lies outside the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Remove certificates, domains ... and IPv4 address ranges from your inventory.' It uses a specific verb and resource, and distinguishes from the sibling 'asm_management_upload_asm_data' by focusing on removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use: removal limits (up to 500), timing, cascading effects, and a constraint (cannot remove assets uploaded previously). Does not explicitly name an alternative tool, but the inverse relationship with the upload tool is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses the upsert nature, permission requirements, and the critical overwrite behavior when rule_id matches. It could also mention what happens to unspecified fields on update, but the key traits are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a short summary, a critical note, permissions, endpoint, and an example. Every section adds value and the example is essential for understanding the JSON body. It is not overly verbose despite the example and is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with a single array parameter and no output schema, the description is fairly complete: it covers the operation type, permissions, the subtle rule_id behavior, and gives a realistic example. It lacks information about response format or error cases, but those are not critical for basic use with siblings present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides a concrete example request body that demonstrates the structure of request_data and sample values for most fields. It also explains the meaning and behavior of rule_id in prose, which is not obvious from the schema. However, it does not field-by-field explain every parameter, leaving some reliance on the schema's enums.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert or update IOCs' which is a specific verb+resource, and it distinguishes itself from sibling tools like indicators_insert_jsons and indicators_insert_csv by focusing on direct JSON insertion. It also provides the exact endpoint, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use: it's for inserting/updating IOCs with a JSON body, requires Instance Administrator permissions, and warns about rule_id tenant-specific behavior. However, it does not explicitly mention when to use this over the csv or jsons variants, so it lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 behavior by noting the dependency on a specific query initiation endpoint, the parallel query limit, and required licenses. It does not detail the response format, but the purpose is a simple quota check and the description provides adequate context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear title, definition, notes, and an example. It is slightly longer than the minimum but every section contributes meaningful information, and the formatting enhances readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter, no-output-schema tool, the description is complete. It explains what the tool does, the specific condition for usage, a relevant quota limit, required licenses, and provides an example request. No critical information seems missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines zero parameters, and the baseline is 4. The description adds value by showing an example request body with 'request_data': {}, clarifying the expected input shape despite the schema being empty. This is helpful for invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get XQL query Quota' and 'Retrieve the amount of query quota available and used,' providing a specific verb and resource. It is easily distinguished from sibling tools like xql_start_xql_query or xql_get_query_results, which focus on running or fetching query results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context, including the note that the endpoint only works on queries initiated by /public_api/v1/xql/start_xql_query/ and mentions the parallel query limit. It does not explicitly name alternative tools for different scenarios, but the context is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 explains that the tool returns a catalog grouped by category and includes tool names and summaries, which is informative. It implies a read-only operation but does not explicitly state 'no side effects' or mention any access requirements. For a simple discovery tool, this is adequate, though explicit non-destructiveness would be better.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the key term 'Discovery tool,' and every sentence adds value. The first sentence states what it returns, and the second gives usage guidance and mentions filtering. There is no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, no annotations), the description is complete enough. It describes the return content (names and summaries) and the grouping/filtering behavior. It does not mention error handling or permissions, but for a discovery tool, these are less critical. The description covers all necessary contextual information for an agent to understand and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a detailed description of the 'tag' parameter, including case-insensitivity and examples. The tool description simply repeats 'Optionally filter by a tag substring,' adding no new meaning beyond what the schema provides. Since schema coverage is 100%, the baseline is 3, and the description does not exceed that baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it is a 'Discovery tool' that returns the catalog of all available XSIAM operations, grouped by category, with each tool's name and summary. This is a specific verb+resource combination (returns catalog) and differentiates it from the sibling tools, which are actual operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to 'Use this to find the right tool before calling it,' which is clear guidance on when to use this tool. It also mentions the optional filtering capability, giving context for narrowing the search. This effectively tells the agent to use it as a discovery mechanism prior to invoking other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the rate limit (600 alerts per minute), required license, and prerequisite mapping, which are important operational constraints. It does not mention error behavior or response structure, but the core traits are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it starts with a clear title-equivalent, then a concise purpose statement, followed by rate limit, license, endpoint, and a comprehensive example. Every section adds value, and the example is relevant despite its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter insertion tool, the description is nearly complete, covering prerequisites, rate, and format. The only notable gap is the absence of any mention of the response format or success/failure indicators, which could matter in absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema's parameter description is minimal, yet the tool description includes a detailed example request body with actual CEF strings and nested JSON structure, far exceeding what the schema offers. This example makes the expected input format unambiguous and highly actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Upload alerts in CEF format from external alert sources', identifying the specific action (upload), resource (alerts), and unique format (CEF). It distinguishes this tool from sibling alert operations like alerts_insert_parsed_alerts by highlighting CEF format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: alerts must be in CEF format, field mapping is a prerequisite, and specific premium licenses are required. However, it does not explicitly name alternative tools or exclusion criteria (e.g., when to use alerts_insert_parsed_alerts instead), so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It discloses the internal call to tenant-info and the result type (whether auth works), but does not detail error handling or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the primary action, and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter health check with no output schema, the description covers the essential information: what it checks, how it does it, and what it reports. It also gives a usage recommendation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 description mentions the endpoint and purpose, but there is no rich parameter semantics to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: checking connectivity and credentials against the XSIAM tenant via the tenant-info endpoint. It is specific and distinct from siblings by emphasizing authentication status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear guidance to run this tool first to confirm configuration, which establishes a priority context. However, it does not explicitly name alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral constraints: maximum 10,000 entries returned, three-minute timeout, license requirements, and filter matching semantics (AND within a block, OR across blocks). This goes well beyond a basic operation description and adds value since no annotations are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. It uses a short paragraph plus bullet points for notes, making it easy to scan. Every sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential behavioral aspects: limits, timeout, filtering semantics, and license. There is no output schema, but the description is sufficient for an agent to select and invoke the tool. A minor gap is the lack of response format details, but overall it is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the 'filters' parameter by explaining the AND/OR block semantics and the behavior when no filters are specified. It also references the 10,000-entry limit relevant to the 'limit' parameter. While it does not explicitly name dataset_name or limit, the schema provides descriptions for those, and the description compensates for the critical filter logic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get data from a lookup dataset' with a specific verb and resource, and the filtering semantics are precisely explained. It distinguishes itself from sibling tools like xql_lookups_add_data and xql_lookups_remove_data by focusing on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage is clear: this tool retrieves data from lookup datasets with optional filters. It explains filtering behavior and defaults, but it does not explicitly mention when to prefer it over alternatives like xql_query or provide exclusions. The context is still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![xsiam-mcp MCP server](https://glama.ai/mcp/servers/CoveoSec/xsiam-mcp/badges/card.svg)](https://glama.ai/mcp/servers/CoveoSec/xsiam-mcp)

Score Badge

Copy to your README.md:

[![xsiam-mcp MCP server](https://glama.ai/mcp/servers/CoveoSec/xsiam-mcp/badges/score.svg)](https://glama.ai/mcp/servers/CoveoSec/xsiam-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/CoveoSec/xsiam-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server