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

The description adds valuable behavioral context beyond the destructiveHint annotation. It discloses that comments support Markdown formatting, specifies required permissions ('Manage Alerts'), and outlines the return structure (success boolean, comment info, error message). This compensates well for the annotation's limited information, though it doesn't mention rate limits or side effects.

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

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

The description is front-loaded with the core purpose, followed by formatting details, return values, and permissions. It's efficiently structured in three clear sections, though the return format listing could be slightly more concise. Overall, it's well-organized with minimal waste.

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

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

Given the presence of an output schema (implied by the return format description), 100% parameter schema coverage, and annotations, the description is complete. It covers the tool's purpose, behavioral traits (formatting, permissions, returns), and usage context adequately for this mutation tool.

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

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

With 100% schema description coverage, the input schema already fully documents the two parameters (alert_id and comment). The description doesn't add any parameter-specific details beyond what's in the schema, so it meets the baseline of 3 without providing extra semantic value.

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

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

The description explicitly states the verb 'Add' and the resource 'comment to a Panther alert', clearly distinguishing it from sibling tools like list_alert_comments (which lists comments) and update_alert_assignee/status (which modify other alert properties). It specifies the action and target precisely.

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

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

The description implies usage when needing to comment on an alert, but doesn't explicitly state when to use this versus alternatives like list_alert_comments for viewing comments. It mentions Markdown formatting as a feature, which provides some context, but lacks explicit guidance on prerequisites or exclusions beyond the permissions note.

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

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

Annotations indicate idempotentHint=true and destructiveHint=true, which the description aligns with by describing updates. The description adds valuable context beyond annotations: it specifies the maximum alert count (25), details the return structure, and mentions required permissions ('Manage Alerts'), enhancing behavioral understanding without contradiction.

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

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

The description is well-structured and front-loaded with the core purpose, followed by usage details and return values. It is appropriately sized with no redundant sentences, though the return value section is detailed but necessary for clarity.

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

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

Given the tool's complexity (bulk updates with destructive potential), the description is complete: it covers purpose, usage constraints, permissions, return structure, and parameter requirements. With annotations and an output schema present, it provides all necessary context for effective tool invocation.

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

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

With 100% schema description coverage, the schema fully documents all parameters. The description adds minimal semantic value beyond the schema, such as noting that at least one update field is required, but does not provide additional syntax or format details. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('bulk update multiple alerts') and resources ('alerts'), distinguishing it from siblings like 'update_alert_assignee' or 'update_alert_status' by emphasizing bulk operations. It explicitly lists the fields that can be updated (status, assignee, comment).

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

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

The description provides clear context for when to use this tool ('efficiently update multiple alerts at once') and specifies that at least one update field must be provided. However, it does not explicitly mention when to use alternatives like individual update tools or exclusions, though the bulk nature implies it's for batch operations.

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

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

Annotations indicate idempotentHint=true and destructiveHint=true, which the description does not contradict. The description adds value by specifying the permission requirements, which are not covered by annotations. It could provide more behavioral context (e.g., effects on alerts, rate limits), but with annotations present, the bar is lower, and the permission info is useful.

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

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

The description is two sentences, front-loaded with the main action and followed by permission details. Every sentence provides essential information without redundancy, making it efficient and well-structured.

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

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

Given the tool's complexity (destructive mutation with permissions), annotations cover idempotency and destructiveness, and an output schema exists, the description is mostly complete. It includes permission requirements but could benefit from more context on outcomes or error handling. However, with output schema handling return values, it's sufficient.

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

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

Schema description coverage is 100%, with clear descriptions for both parameters (detection_id and detection_type). The description does not add any additional semantic information beyond what the schema provides, such as explaining parameter interactions or edge cases. Baseline is 3 when schema coverage is high.

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

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

The description clearly states the specific action ('Disable a Panther detection') and the mechanism ('by setting enabled to false'), making the purpose explicit. It distinguishes this tool from sibling tools like 'get_detection' or 'list_detections' by focusing on modification rather than retrieval.

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

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

The description includes permission requirements ('Permissions:{"any_of": ["Manage Rules", "Manage Policies"]}'), providing clear context for when to use this tool based on user access. However, it does not explicitly mention when not to use it or name alternatives (e.g., compared to other update tools), which prevents a perfect score.

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

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

Annotations provide readOnlyHint=true, indicating a safe read operation. The description adds valuable behavioral context beyond this: it explains the internal process (fetches stream IDs, retrieves latest response text), discloses permission requirements ('Run Panther AI'), and details the return structure. This enriches understanding without contradicting annotations.

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

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

The description is appropriately sized and front-loaded, with the core purpose stated first. However, the 'Returns:' section is somewhat redundant given the output schema, and the permission note could be integrated more smoothly, slightly reducing efficiency.

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

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

Given the tool's complexity (involves multi-step retrieval), rich annotations (readOnlyHint), and the presence of an output schema, the description is complete. It covers the purpose, process, permissions, and return values, providing sufficient context for an agent to use it effectively without over-explaining structured data.

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

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

Schema description coverage is 100%, with the parameter 'alert_id' well-documented in the schema. The description adds no additional parameter semantics beyond what the schema provides (e.g., format examples or constraints), so it meets the baseline of 3 for high schema coverage without extra value.

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

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

The description clearly states the specific action ('retrieve'), resource ('latest AI triage summary'), and scope ('for a specific Panther alert'). It distinguishes this tool from siblings like 'get_alert' (which retrieves general alert details) and 'start_ai_alert_triage' (which initiates triage generation), making the purpose unambiguous and well-differentiated.

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

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

The description implies usage context by specifying it retrieves 'the most recently generated AI triage analysis for an alert,' suggesting it should be used after triage has been initiated. However, it doesn't explicitly state when NOT to use it (e.g., if no triage exists) or name alternatives like 'start_ai_alert_triage' for generating triage, leaving some guidance gaps.

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

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

Annotations provide readOnlyHint=true, indicating a safe read operation. The description adds value by specifying required permissions ('Read Alerts'), which is not covered by annotations, enhancing transparency about access needs. It doesn't describe rate limits or return format, but with annotations and an output schema, this is acceptable.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by essential permission details. Both sentences earn their place by providing critical information without redundancy, making it efficient and well-structured.

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

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

Given the tool's simplicity (1 parameter, read-only operation), annotations cover safety, schema fully documents inputs, and an output schema exists for return values. The description adds permissions context, making it complete enough for an agent to understand and invoke the tool correctly without gaps.

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

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

Schema description coverage is 100%, with the parameter 'alert_id' fully documented in the schema. The description adds no additional parameter details beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly states the verb ('Get detailed information') and resource ('about a specific Panther alert by ID'), making the purpose explicit. It distinguishes from siblings like 'list_alerts' (which lists multiple alerts) and 'get_alert_events' (which fetches events for an alert), establishing a specific scope for retrieving a single alert's details.

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

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

The description implies usage context by specifying 'by ID' and mentioning permissions, which helps identify when to use this tool (e.g., for a known alert ID). However, it lacks explicit guidance on when to choose this over alternatives like 'list_alerts' for browsing or 'get_alert_events' for event data, leaving some ambiguity in sibling differentiation.

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

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

Annotations provide readOnlyHint=true, but the description adds valuable behavioral context beyond this: it notes that event order is not guaranteed and that pagination is unsupported to prevent expensive queries. This enhances transparency about limitations and performance considerations, though it could mention rate limits or authentication needs.

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

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

The description is well-structured and front-loaded, starting with the core purpose, followed by important behavioral notes and return value details. Each sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

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

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

Given the tool's complexity (a read operation with two parameters), the presence of annotations (readOnlyHint) and an output schema (implied by the Returns section), the description is complete. It covers purpose, behavioral traits, and return values, providing sufficient context for effective tool selection and invocation.

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

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

The input schema has 100% description coverage, clearly documenting both parameters (alert_id and limit). The description does not add any additional meaning or semantics beyond what the schema provides, such as explaining parameter interactions or constraints. With high schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('events for a specific Panther alert'), distinguishing it from siblings like 'get_alert' (which retrieves alert metadata) and 'get_alert_event_stats' (which provides statistics). It precisely defines what the tool does without being vague or tautological.

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

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

The description provides clear context for when to use this tool (to retrieve events for a specific alert) and implicitly distinguishes it from alternatives by specifying its scope. However, it does not explicitly state when not to use it or name specific sibling tools as alternatives, such as 'list_alerts' for broader queries.

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

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

Annotations provide readOnlyHint=true, indicating a safe read operation. The description adds valuable behavioral context beyond this: it specifies the tool aggregates data into time windows, collects unique entities and metadata, orders results chronologically with most recent first, and returns paginated results (has_next_page, next_cursor). It also mentions permissions requirements ('Query Data Lake'), which isn't covered by annotations. No contradictions with annotations exist.

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

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

The description is well-structured with clear paragraphs: purpose, parameter context, result ordering, and return format. It's appropriately sized for a complex analytical tool. However, the detailed return format section (8 bullet points) is somewhat lengthy and could be streamlined, as some of this information might be better covered by an output schema (which exists).

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

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

Given the tool's analytical complexity, the description is complete: it explains the purpose, behavioral traits (aggregation, ordering, pagination), and permissions. With annotations covering safety (readOnlyHint) and an output schema existing (implied by context signals), the description doesn't need to detail return values extensively. It provides sufficient context for an agent to understand when and how to use this tool effectively.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters (alert_ids, time_window, start_date, end_date). The description adds minimal parameter semantics beyond the schema: it mentions time windows are 'configurable from 1-60 minutes' (implied by time_window) and that results help identify patterns. However, it doesn't provide additional context about parameter interactions or usage examples beyond what's in the schema descriptions.

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

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

The description clearly states the tool's purpose as analyzing patterns across multiple alerts by aggregating event data into time-based groups. It specifies the verb 'analyze' and resource 'alert event stats', distinguishing it from sibling tools like get_alert (single alert) or get_alert_events (raw events). The description provides specific details about what gets aggregated (entities, metadata) and the goal (identify related activities).

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

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

The description implies usage context by stating it helps 'identify related activities' and 'identify temporal patterns', suggesting it's for pattern analysis across alerts. However, it doesn't explicitly state when to use this tool versus alternatives like get_alert_events (which might return raw events) or query_data_lake (which might allow more flexible queries). The guidance is clear but lacks explicit sibling differentiation.

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

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

Annotations provide readOnlyHint=true, indicating this is a safe read operation. The description adds value by specifying the return structure (e.g., success flag, breakdowns, totals) and permissions ('Read Panther Metrics'), which aren't covered by annotations. However, it doesn't disclose other behavioral traits like rate limits, caching, or error handling. With annotations handling the safety profile, the description offers moderate additional context, aligning with a baseline score.

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

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

The description is appropriately sized and front-loaded, starting with the core purpose. The 'Returns' section is detailed but necessary for clarity, and the permissions note is concise. However, the structure could be slightly improved by integrating the permissions into the main flow or using bullet points for better readability, but overall, it's efficient with minimal waste.

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

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

Given the tool's complexity (3 parameters, 100% schema coverage, annotations, and an output schema implied by the return description), the description is fairly complete. It explains what the tool does, the return format, and permissions. The output schema details in the description compensate for the lack of a formal output schema field. However, it could benefit from more usage context or examples to fully guide the agent, keeping it from a perfect score.

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

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

Schema description coverage is 100%, with each parameter (start_date, end_date, interval_in_minutes) well-documented in the schema. The description doesn't add any parameter-specific details beyond what's in the schema, such as explaining how the interval affects the 'bytes_processed' list. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description provides no extra parameter semantics.

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

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

The description clearly states the tool's purpose: 'Retrieves data ingestion metrics showing total bytes processed per log type and source, helping analyze data volume patterns.' It specifies the verb ('Retrieves'), resource ('data ingestion metrics'), and scope ('per log type and source'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_rule_alert_metrics' or 'get_severity_alert_metrics', which also retrieve metrics but for different aspects, so it doesn't reach the highest score.

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

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

The description provides no guidance on when to use this tool versus alternatives. It mentions analyzing 'data volume patterns,' but doesn't specify scenarios, prerequisites, or exclusions. For example, it doesn't clarify if this is for real-time monitoring, historical analysis, or how it compares to other metrics tools in the sibling list. This lack of context leaves the agent without clear usage direction.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context: it specifies the permissions required ('View Rules'), which isn't covered by annotations. However, it doesn't disclose other behavioral traits like rate limits, error conditions, or what 'complete' information entails beyond the schema. No contradiction with annotations exists.

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

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

The description is appropriately sized with three sentences that are front-loaded: the first states the purpose, the second elaborates on returns, and the third adds permissions. There's minor redundancy between the first two sentences, but overall it's efficient with zero waste.

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

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

Given the tool's complexity (simple read operation), annotations cover safety, schema covers parameters fully, and an output schema exists (so return values are documented), the description is mostly complete. It adds permissions context, which is valuable. However, it lacks guidance on usage versus siblings, which is a minor gap in this context.

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

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

Schema description coverage is 100%, with the parameter 'data_model_id' fully documented in the schema. The description adds no additional meaning about parameters beyond what the schema provides (e.g., no examples or usage notes). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.

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

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

The description clearly states the tool's purpose: 'Get detailed information about a Panther data model, including the mappings and body' and 'Returns complete data model information including Python body code and UDM mappings.' This specifies the verb ('Get'), resource ('Panther data model'), and scope of information returned. However, it doesn't explicitly differentiate from sibling tools like 'list_data_models' or 'get_detection' beyond the data model focus.

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

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

The description provides no guidance on when to use this tool versus alternatives. It mentions permissions ('View Rules'), but this doesn't help choose between this and sibling tools like 'list_data_models' (for listing) or 'get_detection' (for other resources). There's no explicit when/when-not context or named alternatives.

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

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

Annotations declare readOnlyHint=true, which the description doesn't contradict. The description adds value by specifying required permissions ('View Rules', 'View Policies'), which aren't covered by annotations. However, it lacks other behavioral details like rate limits, error handling, or output format, keeping it at a baseline level with some added context.

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

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

The description is concise and front-loaded, with two sentences that directly state the purpose and permissions. There's no wasted text, though it could be slightly more structured (e.g., separating purpose from permissions).

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

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

Given the tool's moderate complexity (read operation with permissions), 100% schema coverage, annotations, and an output schema, the description is reasonably complete. It covers purpose and permissions, though it lacks usage guidelines. The output schema handles return values, so the description doesn't need to explain them.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain 'detection body and tests' in relation to parameters). This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Get detailed information about a Panther detection, including the detection body and tests.' It specifies the verb ('Get detailed information') and resource ('Panther detection'), making the function clear. However, it doesn't explicitly differentiate from siblings like 'list_detections' or 'get_alert', which would require a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It mentions permissions but doesn't specify use cases, prerequisites, or exclusions compared to sibling tools like 'list_detections' or 'get_alert'. This leaves the agent without context for selection.

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

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

Annotations provide readOnlyHint=true, and the description doesn't contradict this. It adds valuable context beyond annotations: it specifies the return content ('complete global helper information including Python body code and usage details') and includes permissions requirements ('Permissions:{'all_of': ['View Rules']}'), which are not covered by annotations. However, it doesn't mention rate limits or other behavioral traits.

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

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

The description is appropriately sized with three sentences: purpose, return details, and permissions. It's front-loaded with the core purpose, and each sentence adds value (return specifics and permissions). Minor improvement could be merging sentences for tighter flow, but it's efficient with zero waste.

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

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

Given the tool's simplicity (1 parameter, 100% schema coverage, read-only operation, and an output schema exists), the description is complete. It covers purpose, return content, and permissions, which are sufficient for an AI agent to understand and invoke the tool correctly without needing to explain return values (handled by output schema).

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

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

Schema description coverage is 100%, with the helper_id parameter well-documented in the schema. The description adds no additional parameter semantics beyond what the schema provides (e.g., no format details or examples beyond the schema's examples). Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the specific action ('Get detailed information') and resource ('Panther global helper by ID'), distinguishing it from sibling tools like list_global_helpers (which lists helpers) and other get_* tools that fetch different resources. The verb+resource combination is 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.

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

The description implies usage when detailed information about a specific global helper is needed, but it doesn't explicitly state when to use this tool versus alternatives like list_global_helpers (for browsing) or other get_* tools. No exclusions or prerequisites are mentioned beyond the permissions requirement.

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

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds valuable behavioral context beyond this by explaining that HTTP log sources are for 'collecting logs via HTTP endpoints/webhooks' and that the tool provides 'detailed configuration information for troubleshooting and monitoring.' It also includes permissions information ('View Log Sources'), which is crucial for access control. No contradictions with annotations exist.

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

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

The description is well-structured with a clear purpose statement, context about HTTP log sources, and detailed return value documentation. It's appropriately sized for a tool with complex output, though the extensive Returns section could be streamlined since an output schema exists. Most sentences earn their place, but there's some redundancy in parameter documentation.

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

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

Given the tool's complexity (single parameter but detailed output), the description is highly complete. It explains the purpose, provides context about HTTP log sources, documents the parameter, and details the return structure comprehensively. With annotations covering read-only behavior and an output schema likely available, the description adds all necessary contextual information without gaps.

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

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

The input schema has 100% description coverage, with the parameter 'source_id' well-documented in the schema. The description adds minimal value by restating 'The ID of the HTTP log source to retrieve' in the Args section, which is redundant with the schema. However, it doesn't provide additional semantic context beyond what the schema already offers, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Get detailed information about a specific HTTP log source by ID.' It specifies the verb ('Get'), resource ('HTTP log source'), and scope ('by ID'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_log_sources' beyond the 'by ID' detail, which is why it doesn't reach a perfect score.

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

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

The description provides implied usage context by stating that HTTP log sources 'are used to collect logs via HTTP endpoints/webhooks' and that this tool is for 'troubleshooting and monitoring HTTP log source integrations.' However, it lacks explicit guidance on when to use this tool versus alternatives like 'list_log_sources' or other sibling tools, leaving the agent to infer based on the 'by ID' requirement.

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

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

The annotations provide readOnlyHint=true, and the description adds valuable behavioral context beyond this: it discloses the response size limitation ('Limited to 5 schemas at a time'), includes permissions requirements ('Permissions:{'all_of': ['View Rules']}'), and details the return structure. This enriches the agent's understanding without contradicting annotations.

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

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

The description is well-structured and appropriately sized, with the purpose and key constraints stated upfront, followed by a detailed return format. Every sentence adds value, though the return details are extensive; it could be slightly more concise by summarizing the return structure rather than listing all fields.

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

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

Given the tool's complexity (detailed schema retrieval with permissions), the description is complete: it covers purpose, usage constraints, behavioral traits, and a comprehensive return format. With annotations covering read-only nature and an output schema implied by the detailed return description, no significant gaps remain for agent understanding.

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

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

The input schema has 100% description coverage, clearly documenting the 'schema_names' parameter with its description, examples, and constraints. The description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the specific action ('Get detailed information') and resource ('specific log type schemas'), including the scope ('full specifications'). It distinguishes from sibling tools like 'list_log_type_schemas' by focusing on detailed retrieval rather than listing.

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

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

The description provides clear context by specifying the limitation ('Limited to 5 schemas at a time') and implicitly suggests usage when detailed schema information is needed. However, it does not explicitly state when to use this tool versus alternatives like 'get_table_schema' or 'list_log_type_schemas', missing explicit exclusions or named alternatives.

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

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

The annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context about the diagnostic purpose (permission errors, API token needs) which goes beyond the annotations. However, it doesn't disclose other behavioral traits like rate limits, authentication requirements beyond the implied token context, or response format details that aren't covered by the 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.

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

The description is perfectly concise with two clear sentences that each serve distinct purposes: the first states what the tool does, the second explains when to use it. There's zero wasted language, and the most important information (the tool's function) comes first.

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

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

For a simple read-only tool with 0 parameters, annotations covering safety, and an output schema, the description provides adequate context. It explains the purpose and practical use cases well. The main gap is that it doesn't explicitly mention what information the permissions include or the format of the response, but the output schema should cover that.

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

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

With 0 parameters and 100% schema description coverage, the schema fully documents the lack of inputs. The description doesn't need to explain parameters, and it appropriately focuses on the tool's purpose and usage instead. A baseline of 4 is appropriate for zero-parameter tools where the description adds value elsewhere.

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

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

The description clearly states the verb 'Get' and resource 'current user's permissions', making the purpose explicit. However, it doesn't distinguish this tool from potential sibling permission-related tools (none are listed in siblings, but the agent might assume others exist). The diagnostic use case adds specificity but doesn't fully differentiate from hypothetical alternatives.

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

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

The description provides clear context for when to use this tool: 'to diagnose permission errors and determine if a new API token is needed'. This gives practical guidance on appropriate scenarios. However, it doesn't explicitly state when NOT to use it or mention alternatives (though no obvious permission-related siblings exist in the provided list).

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

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

Annotations declare readOnlyHint=true, which the description does not contradict. The description adds value by specifying the return content ('complete role information including all permissions and settings') and permission requirements ('Permissions: {"all_of": ["Read User Info"]}'), which are not covered by annotations. It provides useful behavioral context beyond the annotations.

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

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

The description is front-loaded with the core purpose, followed by return details and permissions. Every sentence adds value without redundancy, and it is appropriately sized for a simple tool with one parameter and clear annotations. No wasted words or unnecessary elaboration.

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

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

Given the tool's low complexity (1 parameter, 100% schema coverage), presence of annotations (readOnlyHint), and an output schema, the description is complete. It covers purpose, return content, and permissions, which are sufficient for an AI agent to understand and invoke the tool correctly without needing to explain return values (handled by output schema).

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

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

Schema description coverage is 100%, with the parameter 'role_id' fully documented in the schema. The description does not add any additional meaning or details about the parameter beyond what the schema provides, such as format constraints or examples. Baseline score of 3 is appropriate as the schema handles parameter documentation adequately.

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

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

The description clearly states the specific action ('Get detailed information') and resource ('Panther role by ID'), distinguishing it from sibling tools like 'list_roles' (which lists roles) and 'get_user' (which fetches user info). It precisely defines the tool's function without being vague or tautological.

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

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

The description implies usage when detailed role info is needed (vs. 'list_roles' for listing), but does not explicitly state when to use this tool over alternatives or any exclusions. It provides clear context but lacks explicit guidance on when-not scenarios or named alternatives.

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

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

The annotations already declare readOnlyHint=true, indicating this is a safe read operation. The description adds valuable context beyond annotations by specifying the scope ('for ALL alert types'), mentioning the permission requirement ('Permissions:{"all_of": ["Read Panther Metrics"]}'), and describing the grouping behavior ('grouped by detection rule'). It doesn't contradict annotations and provides useful 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.

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

The description is well-structured with purpose first, usage guidance second, and return format third. The permission information is appended but relevant. While efficient, the return format section could be more concise since an output schema exists, making some of that detail redundant.

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

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

Given the tool's complexity (aggregated metrics with time grouping), the description provides complete context. It covers purpose, differentiation from siblings, permission requirements, and behavioral scope. With both annotations (readOnlyHint) and an output schema present, the description appropriately focuses on operational context rather than repeating structured information.

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

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

With 100% schema description coverage, the input schema already fully documents all 4 parameters with clear descriptions and examples. The description doesn't add any parameter-specific information beyond what's in the schema, but it does provide context about the time period grouping. This meets the baseline expectation when schema coverage is complete.

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

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

The description clearly states the tool's purpose with specific verbs ('Gets alert metrics grouped by detection rule') and resources ('for ALL alert types, including alerts, detection errors, and system errors within a given time period'). It explicitly distinguishes from the sibling tool 'list_alerts' by specifying this is for aggregated metrics rather than specific alert details.

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

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

The description provides explicit guidance on when to use this tool ('Use this tool to identify hot spots in alerts') versus alternatives ('use list_alerts for specific alert details'). It clearly differentiates this aggregated metrics tool from the detailed listing sibling tool, giving the agent clear decision criteria.

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

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

The annotations provide readOnlyHint=true, indicating a safe read operation. The description adds valuable context beyond this by detailing the return structure, including success status and error handling, and specifying required permissions ('Query Data Lake'), which enhances transparency about access requirements and response behavior.

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

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

The description is well-structured and front-loaded with the core purpose, followed by details on returns and permissions. It is appropriately sized with no redundant information, though the permissions note could be integrated more smoothly into the flow.

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

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

Given the tool's complexity (single parameter, read-only operation), the description is complete. It includes purpose, detailed return values, and permissions, and with an output schema present, it does not need to explain return values further. The annotations cover safety, and the schema handles parameters fully.

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

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

The input schema has 100% description coverage, fully documenting the single parameter 'query_id' with its UUID format and examples. The description does not add any additional semantic details about the parameter beyond what the schema provides, so it meets the baseline score of 3.

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

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

The description clearly states the tool's purpose with a specific verb ('Get detailed information') and resource ('about a specific scheduled query by ID'), distinguishing it from sibling tools like 'list_scheduled_queries' which returns a list rather than detailed information for a single query.

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

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

The description implies usage context by specifying that it fetches information for a specific scheduled query by ID, but does not explicitly state when to use this tool versus alternatives like 'list_scheduled_queries' or provide exclusions. The permissions requirement is noted, but no explicit guidance on tool selection is given.

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

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

While annotations already declare readOnlyHint=true, the description adds valuable behavioral context about data inconsistencies ('these metrics combine errors and alerts, so there may be inconsistencies from what list_alerts returns') and includes permission requirements. It doesn't contradict annotations and provides useful operational insights beyond the structured data.

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

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

The description is well-structured and appropriately sized, with purpose, usage guidance, behavioral notes, and return format clearly separated. While efficient, the inclusion of detailed return value documentation could be considered slightly redundant given the presence of an output schema.

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

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

Given the tool's complexity, the description provides excellent context with purpose, usage guidelines, behavioral notes, and return format. With both comprehensive annotations (readOnlyHint) and an output schema available, the description focuses appropriately on the value-added information needed for effective tool selection and use.

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

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

With 100% schema description coverage, the input schema already comprehensively documents all 5 parameters. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation without providing additional semantic value.

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

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

The description clearly states the tool's purpose with specific verbs ('Gets alert metrics grouped by severity') and resources ('for rule and policy alert types within a given time period'). It explicitly distinguishes from the sibling 'list_alerts' tool, making the differentiation clear and specific.

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

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

The description provides explicit guidance on when to use this tool ('to identify hot spots in your alerts') versus alternatives ('use the list_alerts tool for specific details'). It also includes important context about data inconsistencies between tools, offering clear usage boundaries.

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

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

Annotations provide readOnlyHint=true, but the description adds valuable context beyond this: it specifies the return format in detail (including success flag, table metadata, columns list with name/type/description), mentions permissions requirement ('Permissions:{'all_of': ['Query Data Lake']}'), and explains limitations (e.g., nested structures only shown as 'object' type). No contradiction with annotations.

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

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

The description is well-structured with clear sections (purpose, important notes, workflow example, return format, permissions). While slightly longer due to the detailed example, every sentence adds value—no wasted words. It could be slightly more concise but remains highly efficient.

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

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

Given the tool's complexity (metadata retrieval with permissions), rich annotations (readOnlyHint), and detailed output schema (implied by the return format description), the description is complete. It covers purpose, usage guidelines, behavioral context, permissions, and integration with other tools, leaving no gaps for agent understanding.

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

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

Schema description coverage is 100%, providing clear documentation for both parameters. The description doesn't add additional parameter semantics beyond what's in the schema, but it contextually explains how parameters fit into the workflow (e.g., using 'panther_logs.public' and 'aws_cloudtrail' in the example). Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the specific action ('Get column details') and resource ('for a specific data lake table'), distinguishing it from sibling tools like 'list_database_tables' (which lists tables) or 'get_log_type_schema_details' (which provides log structure details). It precisely defines 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.

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

The description explicitly provides when to use this tool ('to get column names/types') and when to use an alternative ('For writing optimal queries, ALSO call get_panther_log_type_schema()'), including a detailed example workflow. It clearly differentiates this tool's role from complementary tools.

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

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

Annotations provide readOnlyHint=true, and the description adds valuable context beyond this: it specifies the permission requirement ('Permissions:{'all_of': ['Read User Info']}') and details what information is returned (email, names, role, etc.). This enhances understanding of behavioral traits without contradicting annotations.

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

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

The description is appropriately sized and front-loaded with the core purpose, followed by return details and permissions. It avoids redundancy, but the formatting with extra spaces slightly affects structure. Overall, it's efficient with minimal waste.

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

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

Given the tool's low complexity, high schema coverage, presence of annotations, and an output schema, the description is complete enough. It covers purpose, return values, and permissions, addressing key contextual needs without unnecessary elaboration.

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

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

Schema description coverage is 100%, with the parameter 'user_id' well-documented in the schema. The description does not add significant meaning beyond the schema, as it only mentions 'by ID' without further details. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the specific action ('Get detailed information') and resource ('a Panther user by ID'), distinguishing it from sibling tools like 'list_users' which returns multiple users. It precisely defines what the tool does without being vague or tautological.

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

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

The description implies usage by specifying 'by ID' and listing returned fields, but does not explicitly state when to use this tool versus alternatives like 'list_users' or other user-related tools. No explicit guidance on prerequisites or exclusions is provided.

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

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

Annotations provide readOnlyHint=true, indicating a safe read operation. The description adds valuable context beyond this: it discloses required permissions ('Read Alerts'), describes the return structure (including success flag, comments list with fields, and error message), and mentions pagination behavior via the 'limit' parameter. This enriches the agent's understanding without contradicting annotations.

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

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

The description is well-structured and front-loaded with the core purpose, followed by return details and permissions. It avoids redundancy, but the return value documentation is somewhat verbose; a more concise format (e.g., bullet points) could improve readability without losing clarity.

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

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

Given the tool's moderate complexity (2 parameters, read-only operation), the description is complete: it covers purpose, return structure, and permissions. With annotations indicating safety and an output schema implied by the detailed return documentation, no critical gaps exist for agent usage. It effectively supplements structured fields without unnecessary repetition.

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

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

Schema description coverage is 100%, with clear descriptions for 'alert_id' and 'limit' parameters. The description does not add semantic details beyond the schema (e.g., it doesn't explain comment ordering or default behaviors). Given the high schema coverage, a baseline score of 3 is appropriate, as the description relies on the schema for parameter documentation.

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

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

The description clearly states the specific action ('Get all comments') and resource ('for a specific Panther alert'), distinguishing it from siblings like 'add_alert_comment' (which creates comments) and 'get_alert' (which retrieves alert details). It precisely defines the tool's scope without ambiguity.

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

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

The description implies usage by specifying the target resource ('Panther alert'), but lacks explicit guidance on when to use this tool versus alternatives like 'get_alert' (which might include comments) or 'add_alert_comment' (for creating comments). No exclusions or prerequisites are mentioned, leaving usage context partially inferred.

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

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

The description adds valuable behavioral context beyond the readOnlyHint annotation. It explains the default date range behavior when detection_id isn't provided, clarifies the relationship between alert_type and subtypes with specific valid combinations, and mentions pagination behavior with cursor/page_size. The permissions requirement ('Read Alerts') is also explicitly stated, which is crucial for authorization.

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

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

The description is overly verbose and poorly structured. It front-loads the purpose but then includes a lengthy parameter documentation section that duplicates schema information. The permissions statement is tacked on at the end without integration. Many sentences (like the detailed parameter explanations) don't earn their place since this information is already in the structured schema.

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

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

Given the tool's complexity (15 parameters, read-only operation, comprehensive filtering), the description is complete. It covers the purpose, key behavioral aspects (defaults, dependencies, pagination), and permissions. With both annotations (readOnlyHint) and an output schema (implied by context signals), the description doesn't need to explain safety or return values, and it provides adequate context for agent usage.

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

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

With 100% schema description coverage, the input schema already documents all 15 parameters thoroughly. The description repeats much of this information (e.g., format examples, default behaviors, valid values) without adding significant new semantic meaning. It does provide slightly more context about subtype dependencies on alert_type, but this is largely redundant with schema examples.

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

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

The description clearly states the tool's purpose with a specific verb ('List') and resource ('alerts from Panther'), distinguishing it from siblings like 'get_alert' (single alert) and 'list_alert_comments' (comments). It also mentions 'comprehensive filtering options' which sets expectations for a rich query interface.

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

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

The description provides clear context for when to use this tool (listing alerts with filtering) and implicitly distinguishes it from siblings through its comprehensive filtering focus. However, it doesn't explicitly state when NOT to use it or name specific alternatives like 'get_alert' for single alerts or 'list_detections' for detection listings.

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

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

The annotations provide readOnlyHint=true, indicating a safe read operation. The description adds value by specifying the return structure (Dict with success, databases, message) and permissions requirement ('Query Data Lake'), which are not covered by annotations. It doesn't mention rate limits or side effects, but with annotations covering safety, this is sufficient for good transparency.

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

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

The description is well-structured and front-loaded, starting with the core purpose, followed by return details and permissions. Every sentence adds value: the first defines the action, the second explains the output format, and the third specifies permissions. There is no wasted text or redundancy.

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

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

Given the tool's simplicity (0 parameters, read-only, with output schema provided), the description is complete. It covers the purpose, output structure, and permissions, which are essential for an agent to use it correctly. The presence of an output schema means the description doesn't need to detail return values, and it adequately addresses the tool's context.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on output and permissions. This meets the baseline of 4 for zero-parameter tools, as it avoids unnecessary repetition.

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

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

The description clearly states the verb ('List') and resource ('all available datalake databases in Panther'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_database_tables' or 'list_data_models', which would require mentioning what this tool does NOT do (e.g., list tables within databases).

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

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

The description provides no guidance on when to use this tool versus alternatives. While it mentions permissions ('Query Data Lake'), it doesn't specify use cases, prerequisites, or comparisons with related tools like 'list_database_tables' for table-level listing or 'query_data_lake' for querying data. This leaves the agent without context for tool selection.

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

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

The annotations already declare readOnlyHint=true, indicating this is a safe read operation. The description adds valuable context beyond annotations by specifying required permissions ('Permissions:{'all_of': ['Query Data Lake']}') and detailing the exact return structure, which provides important behavioral information about authorization needs and output format.

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

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

The description is well-structured and appropriately sized, with clear sections for purpose, requirements, and return values. While slightly longer than minimal, every sentence adds value and the information is front-loaded with the core purpose first.

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

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

Given the tool's moderate complexity, the description provides complete context: clear purpose, usage prerequisites, detailed return structure, and required permissions. With annotations covering safety and an output schema presumably documenting the return format, the description fills all necessary gaps for effective tool use.

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

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

With 100% schema description coverage, the input schema already fully documents the single 'database' parameter. The description doesn't add any additional parameter semantics beyond what's in the schema, but the schema itself provides complete coverage, meeting the baseline expectation.

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

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

The description clearly states the specific action ('List all available tables') and target resource ('in a Panther Database'), distinguishing it from sibling tools like list_databases (which lists databases) and get_table_schema (which gets schema details). It provides a complete picture of what the tool does.

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

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

The description explicitly states when to use this tool ('Only use valid database names obtained from list_databases'), providing clear prerequisites and linking to a specific sibling tool. This gives the agent precise guidance on proper usage context.

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

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

Annotations provide readOnlyHint=true, which the description doesn't contradict. The description adds valuable behavioral context beyond annotations: it discloses pagination behavior ('Returns paginated list'), specifies what metadata is included ('mappings and log types'), and mentions the permission requirement ('Permissions: {"all_of": ["View Rules"]}'). This provides useful operational context that annotations alone don't cover.

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

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

The description is appropriately sized with three focused paragraphs: purpose statement, additional context about data models, and behavioral details. Each sentence adds value without redundancy. The structure is logical with purpose first, though the permissions information might be better integrated rather than appended.

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

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

Given the tool's relative simplicity (list operation with 2 optional parameters), 100% schema coverage, readOnlyHint annotation, and existence of an output schema, the description provides excellent contextual completeness. It covers purpose, behavioral traits (pagination, metadata, permissions), and context about what data models are, making it fully adequate for agent understanding.

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

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

Schema description coverage is 100%, with both parameters (cursor, limit) well-documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema, but doesn't need to since schema coverage is complete. The baseline score of 3 is appropriate when the schema carries the full parameter documentation burden.

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

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

The description clearly states the specific action ('List all data models') and resource ('from your Panther instance'), with additional context about what data models are used for ('used only in Panther's Python rules to map log type schema fields to a unified data model'). It distinguishes from sibling tools like 'get_data_model' by specifying it lists all models rather than retrieving a single one.

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

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

The description implies usage context by mentioning data models are used in Panther's Python rules, but doesn't explicitly state when to use this tool versus alternatives like 'get_data_model' or other list tools. It includes permissions information, which provides some guidance on prerequisites, but lacks explicit when/when-not instructions or named alternatives.

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

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

The description adds valuable behavioral context beyond the readOnlyHint annotation, such as the client-side filtering caveat for 'output_ids' and the efficiency tip for using 'tag'. It also includes permissions information ('View Rules', 'View Policies'), which is not covered by annotations. No contradictions with annotations exist.

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

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

The description is well-structured and front-loaded with the core purpose, followed by important notes and permissions. It avoids unnecessary repetition, but the permissions section could be integrated more smoothly, and the note about client-side filtering is slightly verbose.

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

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

Given the tool's complexity (13 parameters), rich schema coverage (100%), annotations (readOnlyHint), and the presence of an output schema, the description is complete. It covers key behavioral aspects like filtering nuances and permissions, leaving no critical gaps for the agent to understand the tool's use.

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

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

With 100% schema description coverage, the input schema already fully documents all 13 parameters. The description does not add significant semantic details beyond what the schema provides, such as explaining interactions between parameters or edge cases, so it meets the baseline of 3.

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

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

The description clearly states the tool's purpose: 'List detections from your Panther instance with support for multiple detection types and filtering.' It specifies the verb ('List'), resource ('detections'), and scope ('Panther instance'), but does not explicitly differentiate it from sibling tools like 'get_detection' or 'list_alerts', which prevents a perfect score.

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

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

The description provides clear usage context by noting that 'output_ids' filtering is client-side and suggesting 'tag' for more efficient API-level filtering. However, it does not explicitly state when to use this tool versus alternatives like 'get_detection' or 'list_alerts', which would be needed for a score of 5.

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

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

Annotations provide readOnlyHint=true, but the description adds valuable behavioral context: it specifies the return format ('paginated list of global helpers with metadata including descriptions and code') and includes permission requirements ('Permissions:{"all_of": ["View Rules"]}'). This goes beyond what annotations alone provide, though it doesn't mention rate limits or other constraints.

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

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

The description is efficiently structured in three sentences: purpose statement, definition of global helpers, and return format with permissions. Every sentence adds value with zero wasted words, and key information is front-loaded.

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

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

Given the tool has annotations (readOnlyHint), 100% schema coverage, and an output schema (implied by context signals), the description provides excellent completeness. It covers purpose, resource definition, return format, pagination behavior, and permissions - everything needed for an agent to use this tool effectively.

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

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

With 100% schema description coverage, the input schema already fully documents all 5 parameters. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting.

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

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

The description clearly states the verb ('List') and resource ('all global helpers from your Panther instance'), with a helpful definition of what global helpers are ('shared Python functions that can be used across multiple rules, policies, and other detections'). It distinguishes from the sibling tool 'get_global_helper' (singular) by indicating this lists all helpers rather than retrieving a specific one.

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

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

The description provides clear context about when to use this tool ('List all global helpers') and implicitly distinguishes it from 'get_global_helper' (singular retrieval). However, it doesn't explicitly state when NOT to use it or mention alternative tools for similar purposes beyond the implicit sibling distinction.

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

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

The annotations already declare readOnlyHint=true, indicating this is a safe read operation. The description adds the permissions requirement ('View Rules'), which provides useful context beyond annotations. However, it doesn't describe behavioral aspects like pagination behavior (implied by cursor parameter but not explained), rate limits, or what constitutes a 'log source' in Panther's context.

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

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

The description is efficiently structured in two sentences: one stating the core purpose and scope, another providing critical permission information. There's no wasted text, though the permission format could be more natural. It's appropriately sized for a list operation with filters.

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

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

Given the tool has annotations (readOnlyHint), 100% schema coverage, and an output schema (implied by context signals), the description provides adequate context. It covers the core purpose, mentions filtering capability, and includes permission requirements. For a read-only list tool with good structured documentation, this is reasonably complete.

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

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

With 100% schema description coverage, all parameters are well-documented in the schema itself. The description adds no additional parameter information beyond mentioning 'optional filters' generically. This meets the baseline of 3 since the schema carries the full burden of parameter documentation.

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

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

The description clearly states the verb ('List') and resource ('log sources from Panther'), making the purpose immediately understandable. It distinguishes itself from siblings like 'list_alerts' or 'list_detections' by specifying the resource type. However, it doesn't explicitly differentiate from potential similar tools like 'get_log_type_schema_details' beyond the resource name.

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

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

The description mentions 'optional filters' which implies usage when filtering is needed, but provides no explicit guidance on when to use this tool versus alternatives. There's no mention of prerequisites like the required permissions (though those are listed separately), nor comparison to sibling tools like 'get_http_log_source' for specific log source types.

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

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

The annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds valuable context beyond this: it explains what schemas are (transformation instructions), mentions the return structure in detail, and includes permissions requirements. However, it doesn't cover rate limits or pagination behavior.

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

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

The description is efficiently structured with clear sections: purpose explanation, return value details, and permissions. Every sentence adds value without redundancy, and the information is front-loaded with the core purpose stated first.

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

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

Given the tool has comprehensive annotations (readOnlyHint), 100% schema coverage, and a detailed output schema in the description, the description provides complete context. It explains the tool's purpose, return structure, and permissions, making it fully adequate for an agent to understand and use the tool correctly.

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

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

With 100% schema description coverage, the input schema fully documents all 4 parameters. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting.

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

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

The description clearly states the verb 'List' and the resource 'all available log type schemas in Panther', specifying that schemas are transformation instructions for audit logs. It distinguishes from sibling tools like 'get_log_type_schema_details' by indicating this lists all schemas rather than getting details of a specific one.

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

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

The description implies usage for retrieving schemas for data lake and Python rules, but does not explicitly state when to use this tool versus alternatives like 'get_log_type_schema_details' or other list tools. The permissions requirement provides some context but not explicit guidance on tool selection.

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

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

The annotations provide readOnlyHint=true, indicating a safe read operation. The description adds valuable context beyond this: it specifies the return format ('list of roles with metadata including permissions and settings') and includes a permissions requirement ('Read User Info'), which is crucial for the agent to understand access needs. It doesn't mention rate limits or pagination, but with annotations covering safety, this is sufficient.

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

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

The description is appropriately sized with three sentences: purpose statement, return details, and permissions. It's front-loaded with the core functionality. The permissions section is slightly verbose but necessary. No wasted words, though it could be slightly more structured (e.g., bullet points for permissions).

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

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

Given the context: annotations cover safety (readOnlyHint), schema coverage is 100% for parameters, and an output schema exists (implied by 'Returns list of roles'), the description is complete. It adds permissions context and clarifies the return format, which complements the structured data well. No significant gaps remain for this list operation.

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

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

The input schema has 100% description coverage, with clear documentation for all four parameters (name_contains, name, role_ids, sort_dir). The description doesn't add any parameter-specific information beyond what's in the schema, such as explaining interactions between parameters (e.g., 'name' overriding others). This meets the baseline of 3 since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'List all roles from your Panther instance.' It specifies the verb ('List') and resource ('roles'), and distinguishes it from the sibling tool 'get_role' which likely retrieves a single role. However, it doesn't explicitly differentiate from other list_* tools like 'list_users' or 'list_detections', which follow a similar pattern.

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

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

The description implies usage context through the permissions requirement ('Read User Info') and mentions returning metadata, but it doesn't provide explicit guidance on when to use this tool versus alternatives like 'get_role' (for a single role) or other list_* tools. No when-not-to-use scenarios or prerequisites beyond permissions are stated.

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

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

The annotations provide readOnlyHint=true, which the description doesn't contradict. The description adds valuable behavioral context beyond annotations by explaining that SQL content is excluded from responses to prevent token limits, describing the pagination mechanism (cursor-based), and detailing the return structure. However, it doesn't mention rate limits, authentication needs, or other operational constraints.

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

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

The description is well-structured with clear sections: purpose statement, explanation of scheduled queries, important note about SQL exclusion, usage alternative, and detailed return format. While comprehensive, some information in the 'Returns' section could be considered redundant since an output schema exists, making it slightly longer than strictly necessary.

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

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

Given the tool's complexity (list operation with pagination and filtering), the description provides excellent contextual completeness. It explains what scheduled queries are, notes important behavioral constraints (SQL exclusion), provides clear usage guidance with alternatives, details the return structure, and includes permissions information. With both annotations and output schema available, the description adds substantial value without unnecessary repetition.

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

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

With 100% schema description coverage, the input schema already fully documents all three parameters (cursor, limit, name_contains). The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation but doesn't provide additional semantic context about how parameters interact or affect results.

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

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

The description clearly states the tool's purpose with a specific verb ('List') and resource ('all scheduled queries from your Panther instance'), and distinguishes it from the sibling tool get_scheduled_query by noting that SQL content is excluded from list responses. This provides clear differentiation from related tools.

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

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

The description explicitly provides usage guidance by stating when to use this tool ('to list all scheduled queries') versus when to use an alternative ('Use get_scheduled_query() to retrieve the full SQL for a specific query'). It also includes important context about SQL content exclusion to prevent token limits, which helps the agent understand 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.

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

The annotations provide readOnlyHint=true, and the description doesn't contradict this. The description adds valuable behavioral context beyond annotations: it specifies required permissions, describes the pagination mechanism (cursor-based), and details the exact return structure including success indicators and error handling. This goes well beyond what annotations alone provide.

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

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

The description is well-structured and appropriately sized. It starts with the core purpose, then provides detailed return format, and ends with permissions. While the return format section is somewhat lengthy, every sentence provides essential information that earns its place.

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

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

Given the tool's complexity (pagination, permissions, structured returns) and the presence of both annotations and output schema information in the description, the description is complete. It covers purpose, behavior, return format, and permissions - everything needed for an agent to use this tool effectively.

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

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

With 100% schema description coverage, the input schema already fully documents both parameters (cursor for pagination, limit with range constraints). The description doesn't add any additional parameter semantics beyond what's in the schema, but the schema coverage is comprehensive so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with specific verb ('List') and resource ('all Panther user accounts'), making it immediately understandable. It distinguishes itself from sibling tools like 'get_user' (which presumably fetches a single user) by specifying it returns multiple users.

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

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

The description implies usage context through the permissions requirement ('Read User Info'), but doesn't explicitly state when to use this tool versus alternatives like 'get_user' or other list_* tools. No explicit guidance on when-not-to-use or comparisons with siblings is provided.

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

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

The description adds significant behavioral context beyond the readOnlyHint annotation. It explains performance requirements (time filter is 'REQUIRED'), provides detailed pagination behavior, describes query syntax (Snowflake SQL), and outlines return structure. While annotations already indicate it's read-only, the description enriches understanding with practical constraints and operational details that aren't captured in structured fields.

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

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

The description is comprehensive but lengthy and could be more front-loaded. While all content is valuable (macros, best practices, examples, syntax, returns), it's presented as a dense block. The core purpose is clear in the first sentence, but subsequent sections could be better organized or summarized for quicker scanning by an AI agent.

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

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

Given the tool's complexity (SQL querying with performance constraints, pagination, specific syntax) and the presence of both annotations and output schema, the description is remarkably complete. It covers purpose, usage guidelines, behavioral details, parameter context, examples, and return structure. The output schema means the description doesn't need to explain return values in detail, and it appropriately focuses on operational guidance.

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

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

With 80% schema description coverage, the baseline is 3, but the description adds substantial value. It provides extensive context about the 'sql' parameter (time filter requirements, Panther macros, best practices, examples, syntax), explains pagination behavior related to the 'cursor' parameter, and offers performance guidance relevant to 'timeout' and 'max_rows'. This goes well beyond what the schema descriptions provide.

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

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

The description clearly states the tool's purpose: 'Query Panther's security data lake using SQL for log analysis and threat hunting.' This specifies the verb ('query'), resource ('Panther's security data lake'), and context ('log analysis and threat hunting'), distinguishing it from all sibling tools which focus on alerts, detections, users, and other administrative functions rather than direct data lake querying.

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

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

The description provides explicit guidance on when to use this tool: for SQL-based log analysis and threat hunting. It also includes detailed 'Best Practices' and 'Common Examples' sections that guide effective usage, such as starting with summary queries and using time filters. While it doesn't name specific alternatives, the context of sibling tools (which are all about managing alerts, detections, users, etc.) makes it clear this is the primary data querying tool.

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

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

Annotations provide readOnlyHint=true, indicating this is a safe operation. The description adds behavioral context beyond annotations by detailing what the AI triage includes (e.g., analysis of alert metadata, related events, comments) and specifying a timeout parameter with default/max values. However, it does not mention rate limits, authentication needs, or potential side effects like resource consumption, which would enhance transparency further.

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

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

The description is well-structured and front-loaded with the core purpose, followed by details on analysis components and return values. It avoids unnecessary fluff, but the 'Returns' section could be more concise by referencing the output schema instead of listing fields. Overall, most sentences earn their place, though slight trimming is possible.

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

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

Given the tool's complexity (AI triage initiation), the description is complete: it explains the purpose, analysis scope, return structure, and permissions. With annotations (readOnlyHint), a rich input schema (100% coverage), and an output schema (implied by the Returns section), no critical gaps remain. The description effectively complements the structured data without redundancy.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (alert_id, prompt, timeout_seconds) thoroughly. The description does not add significant meaning beyond the schema, such as explaining how the prompt influences AI behavior or typical timeout scenarios. With high schema coverage, the baseline score of 3 is appropriate as the description provides minimal extra parameter insight.

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

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

The description clearly states the tool's purpose: 'Start an AI-powered triage analysis for a Panther alert with intelligent insights and recommendations.' It specifies the action ('start'), resource ('Panther alert'), and scope ('AI-powered triage analysis'), distinguishing it from sibling tools like get_ai_alert_triage_summary (which retrieves results) or get_alert (which fetches basic alert data).

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

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

The description implies usage context by mentioning it initiates AI triage for alerts, but it does not explicitly state when to use this tool versus alternatives like get_ai_alert_triage_summary (which likely retrieves existing triage results). The permissions field ('Run Panther AI') provides some guidance on prerequisites, but no explicit when-not-to-use or alternative tool references are included.

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

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

Annotations provide idempotentHint and destructiveHint, but the description adds valuable context: it specifies the required permission ('Manage Alerts'), clarifies that it works on one or more alerts (batch operation), and documents the exact return structure. This goes beyond what annotations convey about safety and idempotency.

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

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

The description is efficiently structured with a clear purpose statement followed by return value documentation and permissions. Every sentence serves a distinct purpose, though the permissions formatting could be slightly cleaner.

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

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

Given the destructive nature (annotations), batch operation capability, detailed return structure documentation, and explicit permission requirements, the description provides complete context for a mutation tool. The output schema existence means return values are adequately covered.

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

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

With 100% schema description coverage, the input schema already fully documents both parameters. The description doesn't add any additional meaning about parameter usage, constraints, or examples beyond what's in the schema properties, so it meets the baseline for high coverage.

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

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

The description clearly states the specific action ('Update the assignee') and resource ('one or more alerts'), distinguishing it from siblings like 'update_alert_status' which modifies a different alert property. It precisely defines the scope through the assignee's ID.

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

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

The description implies usage for reassigning alerts but doesn't explicitly state when to use this versus alternatives like 'bulk_update_alerts' or 'update_alert_status'. It mentions permissions but doesn't provide contextual guidance on appropriate scenarios for assignee changes.

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

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

The description adds valuable behavioral context beyond annotations: it specifies the required permissions ('Manage Alerts') and details the return structure. While annotations already indicate idempotent and destructive operations, the permission requirement and return format disclosure provide additional operational transparency that annotations alone don't cover.

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

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

The description is efficiently structured with clear sections: purpose statement, return format, and permissions. Each sentence serves a distinct purpose without redundancy. The only minor improvement would be integrating the permissions more smoothly rather than as a separate tag-like statement.

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

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

Given the tool's moderate complexity, comprehensive annotations (idempotent, destructive), complete schema coverage, and explicit output description, the description provides sufficient context. It covers the essential operational aspects including permissions and return format, making it complete for agent understanding despite the lack of a formal output schema.

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

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

With 100% schema description coverage, the schema already fully documents both parameters. The description doesn't add any parameter-specific semantics beyond what's in the schema, so it meets the baseline expectation without providing extra value. The examples in the schema for 'status' are particularly helpful.

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

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

The description clearly states the verb 'update' and the resource 'Panther alerts status', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'update_alert_assignee' or 'bulk_update_alerts', which would require more specific scope definition.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'bulk_update_alerts' or 'update_alert_assignee'. It mentions required permissions but doesn't explain use cases, prerequisites, or exclusion criteria, leaving the agent with insufficient context for tool selection.

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