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

With no annotations, the description fully discloses behavior: it returns per-process data and suggests suppression rules, including the logic for auto-proposing process-wide rules for VPN processes. It does not mention side effects or permissions, but the tool appears read-only.

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

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

The description is a single paragraph but well-organized: first the goal, then specific guidance, then return details. It is informative without being overly verbose, though could be slightly more concise.

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 no output schema, the description fully explains the return structure: per-process count, distinct endpoints, distinct direct IPs, sample detections with dashboard links, and a suggested suppression rule. It also covers the logic for VPN processes. Sibling tools provide additional 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 coverage is 100%, so baseline is 3. The description adds no extra meaning beyond what's in the schema for the two parameters (customer and minCount). The mention of env var fallback is already in the schema description.

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

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

The description clearly states that the tool groups anomalous network-call detections by process, aiming to identify VPN/mesh-networking daemons. It distinguishes from siblings like list_anomalous_network_calls and create_suppression_rule by specifying it returns per-process statistics and suggests suppression rules.

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?

Explicit guidance on when to use (spot VPN daemons) and when not to (do not auto-propose process-wide rules for other processes like dockerd). It also explains that for VPN processes, a single rule suppresses both domain and direct-IP anomalies.

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?

Despite no annotations, the description reveals key behavior: it uses a server-side case-insensitive substring search, returns only matching endpoints, and provides observation data including a dashboard_url. It implies read-only operation with no destructive 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?

Three well-structured sentences: purpose, mechanism, and result presentation instruction with alternative tool. No redundancy, every sentence adds essential information, and the most critical detail (what it does) 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 no output schema, the description explains what is returned (repos/workflows/runs contacted the endpoint, each with dashboard_url). It also covers both parameters and their purpose. The tool is simple (2 params, no nested objects) and the description is sufficient for an agent to invoke it correctly.

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

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

Adds meaning beyond the input schema by explaining that 'owner' is the GitHub org and 'indicator' is a domain or IP substring. Also notes the search is case-insensitive, which is not in the schema. With 100% schema coverage, this extra context is valuable.

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 searches the Harden-Runner org baseline for domain/IP indicators of compromise. It distinguishes itself from the sibling tool 'find_endpoint_calls_in_tenant' by specifying the scope (single org vs tenant-wide), providing a specific verb and resource.

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

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

Explicitly provides an alternative tool ('find_endpoint_calls_in_tenant') for tenant-wide searches, guiding when to use this tool. Also instructs on how to present results with clickable links for each observation, clarifying behavioral expectations.

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

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

With no annotations, description discloses search scope (workflow runs, PRs, default branches) and CI-only limitation. Could mention it's read-only but overall adequate.

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

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

Two sentences, front-loaded with purpose, then adds critical use guidance. No wasted words.

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

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

Missing description of return value or output format. Without output schema, agent cannot infer what results look like. Other aspects covered well.

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

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

Schema coverage is 100%, baseline 3. Adds value by clarifying empty versions array behavior and showing example package name format ('@velora-dex/sdk').

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?

Clearly states it's an 'Am I Affected?' check for npm packages on CI side, distinguishing it from developer machine checks. Uses specific verb 'searches' and resource 'monitored repos'.

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

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

Explicitly guides when to use: 'Org-wide (CI-side)' and provides crucial instruction to call a sibling tool for complete coverage. Includes 'IMPORTANT' note with alternative.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the server's version filter is not applied, requiring client-side filtering. It also mentions the fallback to an environment variable. However, it does not discuss potential rate limits or performance implications, which could be relevant for an enterprise tool.

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

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

The description is well-structured, starting with a clear purpose, then relating to siblings, then detailing parameters. It is somewhat verbose but each sentence adds value. It could be slightly more concise, but overall effective.

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 no output schema and no annotations, the description covers the tool's purpose, usage context, parameter details, and behavior. It explains the relationship to a sibling tool and the client-side filtering requirement. Missing details like output format or error handling, but for a search/check tool, it is fairly complete.

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

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

The input schema already describes all three parameters with 100% coverage. The description adds value by clarifying that 'customer' is optional and falls back to an env var, and that 'versions' performs exact string match and can be omitted to return all installs. This complements the schema well.

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 tool checks for npm package installs on developer machines. It distinguishes itself from the sibling tool 'check_npm_package_exposure' by clarifying that CI and dev machines are independent surfaces, and both must be checked during incident investigation.

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 the tool: when investigating a malicious-package incident, you MUST check both this and 'check_npm_package_exposure'. It also explains optional parameters like customer and versions, and the fallback to environment variable.

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

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

No annotations provided, but description clearly states limitation: 'this only covers CI' and lists scopes (workflow runs, PRs, default branches). Does not discuss rate limits or auth, but scope is fully disclosed.

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

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

Three dense sentences with zero waste. Each sentence adds critical info: scope, version handling, sibling differentiation, and cross-tool guidance.

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

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

Given no output schema, description could mention return format, but purpose and behavior are well-covered. Agent can decide when and how to call correctly. Missing return info is minor.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining empty versions behavior, which matches schema. No additional semantics for other parameters beyond schema.

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

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

Clearly states it's an org-wide CI-side check for a PyPI package, with verb 'check' and resource 'package exposure'. Distinguishes from sibling like check_npm_package_exposure by specifying ecosystem 'pypi'. Explains version matching behavior with empty array.

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

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

Explicitly says use this when ecosystem is 'pypi' and not npm. Provides critical guidance to also call check_python_package_on_dev_machines for complete coverage, since this only covers CI.

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

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

No annotations provided, so description carries full burden. Discloses that version filtering is not applied server-side and must be done client-side via the 'versions' param, and that omitting it returns all installs. Lacks details on rate limits or authentication, but sufficiently covers key behavior for a check tool.

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

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

Two sentences with no waste. Purpose stated first, then behavioral nuance and usage guidance. Every sentence contributes value.

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

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

Given no annotations and no output schema, description adequately covers purpose, behavior (client-side filtering), and relationship to sibling. Parameter usage is clarified. Completely sufficient for agent decision-making.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by clarifying that the 'versions' parameter filters client-side (not server-side) and that omitting it returns all installs. For 'customer', description restates schema info. Overall, description provides moderate added meaning.

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?

Description clearly states it's a check for a PyPI package on developer machines, using action verb 'check' and resource 'PyPI package on dev machines'. Differentiates from sibling check_pypi_package_exposure by specifying it covers dev machines.

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

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

Explicitly says 'for a malicious-PyPI-package incident you MUST check both' this tool and check_pypi_package_exposure, providing clear when-to-use guidance. Also explains independence of exposure surfaces.

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

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

With no annotations, the description fully discloses write nature, confirm requirement, retroactive suppression of past detections, synchronous server-side processing, verification of moved detections, and hardcoded severity action. Lacks mention of idempotency or error states, but is otherwise thorough.

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?

Five sentences, front-loaded, every sentence adds essential guidance. No redundant or extraneous information. 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 (6 params, nested conditions) and no output schema, the description covers prerequisites, behavior, and hardcoded settings. However, it does not specify what the tool returns upon success (e.g., created rule details or confirmation message), which would help an agent understand the response.

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

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

Schema coverage is 100% with each parameter already described. The description adds value by noting that conditions auto-fill owner/repo/workflow/job with '*' and including type-specific keys, and explaining the confirm safety check. This is modest extra context, meeting 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?

Description clearly states 'Create a suppression rule' with a specific verb and resource, distinguishing it from sibling tools like preview, delete, update, list, and get. It also emphasizes this is a WRITE OPERATION.

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

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

Explicitly instructs to call preview_suppression_rule first with same conditions and show the user the expected impact. Also warns about read-only API keys and the need for confirm: true, leaving no ambiguity about prerequisites and execution conditions.

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

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

Discloses critical behavioral traits: it's a write operation, requires confirmation, and importantly notes that deletion does not reverse prior suppressions. This goes beyond the schema and addresses a key side effect.

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

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

Two concise sentences. First sentence states the core purpose; second sentence adds a critical behavioral note. No fluff, 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?

Covers the key behavioral aspect of deletion. Missing is what the return value or success response looks like, but for a delete operation, it is sufficient. The schema fully documents parameters.

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

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

Schema coverage is 100%, so the description adds little beyond what is already in the schema. It mentions the confirm requirement but doesn't elaborate on parameter details.

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

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

Clearly states the verb 'Delete' and the resource 'suppression rule', distinguishing it from sibling tools like create, update, list, and preview. The purpose is unambiguous and specific.

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

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

No explicit instructions on when to use this tool versus alternatives. Implicit from the name, but lacks guidance on prerequisites or timing. The behavioral note about not unsuppressing is useful for decision-making.

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

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

No annotations provided, so description carries full burden. It correctly indicates a read-only descriptive operation but adds no extra behavioral context beyond the obvious.

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?

Single sentence, front-loaded with action and context. Every word earns its place; no 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 no parameters, no output schema, and no annotations, the description fully covers the tool's role and usage 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?

Input schema has no parameters with 100% coverage. Baseline score of 3 is appropriate; description adds no parameter info as none exist.

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

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

Description clearly states verb 'describe' and resource 'what this MCP server can do and how to use it'. It distinguishes from siblings by focusing on overall server capabilities, not specific actions.

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

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

Explicitly says when to call: when user asks 'what can you do?' or is unsure how to start. No exclusions or alternatives needed since it's a unique introductory 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?

With no annotations, the description carries full burden. It discloses fan-out across orgs, bounded concurrency via parameter, and return format including dashboard_url. It also instructs the agent to include clickable links in results. Missing details like rate limits or error handling, but sufficient for safe invocation.

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?

Four sentences with each serving a purpose: purpose, methodology, usage alternative, output presentation rule. Front-loaded with core action. No fluff.

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

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

No output schema, so description explains return structure (flat list, fields). Covers process and constraints. Slight gap in error scenarios or edge cases, but overall complete for a search tool.

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

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

Schema coverage is 100%, baseline 3. The description adds beyond schema by explaining endpoint is a substring, concurrency bounded 1-20, observationsPerOrg caps per-org results. This extra context justifies a 4.

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

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

The description clearly states it finds observations of a network endpoint across all GitHub orgs in a tenant. It specifies the action (find), resource (workflow-run observations), and scope (every org). It also distinguishes itself from sibling tool check_ioc_in_baseline by name-dropping it.

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?

Explicit guidance: 'Use this instead of check_ioc_in_baseline when the user asks "did anyone in our tenant contact X?"' This provides a concrete when-to-use scenario. No when-not-to is stated, but the context is clear.

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

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

No annotations are provided, so the description fully discloses fan-out with bounded concurrency, expected delay (10–60 seconds), return behavior (only matched repos), and the requirement to surface baseline_url as clickable links per repo. It also clarifies the single-org limitation.

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 purpose, then use cases, then technical details. It is efficient with multiple sentences, each earning its place, though it could be slightly more concise without losing meaning.

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

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

Despite no output schema, the description explicitly describes the return format (list of repos with baseline_url) and provides instructions for surfacing results. It also covers concurrency, time expectations, and multi-org workflow, making it fully complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by emphasizing substring matching for endpoint, stating the default concurrency of 10, and bounding concurrency with a max of 50. This goes slightly beyond what the schema provides.

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

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

The description clearly states it finds repos in an org whose Harden-Runner baseline contains a given network endpoint via substring match. It uses a specific verb ('Find') and resource ('repos'), and the context (single-org, substring match) distinguishes it from siblings like check_ioc_in_baseline or check_npm_package_exposure.

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 use-case examples ('which repos contact bun.sh?') and addresses multi-org scenarios by referencing list_tenant_github_orgs. However, it does not directly compare with sibling tools or state when not to use.

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

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

No annotations provided, but description adequately discloses it reads STEP_SECURITY_CUSTOMER env var, is read-only, and non-destructive. Could mention error cases like missing env var, but sufficient for a simple config query.

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

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

Three sentences, each adding value, front-loaded with action. No redundancy or irrelevant details.

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

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

No output schema, but purpose is simple. Description covers purpose, usage trigger, and data source. Minor omission: no mention of error handling for missing env var, but overall 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?

No parameters, so baseline is 4. Description adds value by explaining return value and configuration source.

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

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

The description clearly states the tool returns the tenant identifier and admin console link. The verb 'Return' and resource 'tenant identifier' are specific. Among siblings like 'describe_capabilities', no overlap exists.

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

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

Explicitly states when to call (user queries about tenant) and mentions it reads an environment variable. Does not specify when not to use alternatives, but context is clear.

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

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

The description says 'Read-only,' which hints at safety, but with no annotations, more detail would be beneficial. It does not disclose error handling, authentication needs, or what happens if the rule does not 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 extremely concise at only two short sentences. Every word adds value, no fluff. It is front-loaded and 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?

For a simple get-by-ID tool with no output schema and full schema coverage, the description is minimally adequate. It explains the operation and read-only nature but omits return value context and error scenarios.

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 already provides full descriptions for both parameters (100% coverage). The description adds no additional meaning beyond what the schema provides, so 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 it retrieves a single suppression rule by ID and indicates it is read-only. However, it does not differentiate from sibling tools like list_suppression_rules or preview_suppression_rule, which could cause confusion for an AI agent.

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

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

No guidance is provided on when to use this tool versus alternatives such as list_suppression_rules or preview_suppression_rule. An agent might not know this is appropriate only when a specific rule ID is known.

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

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

No annotations provided; description carries full burden. It describes what the return includes (compromised packages, IOCs), but doesn't explicitly state read-only nature or auth requirements, though implied.

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

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

Two sentences, no filler; second sentence is a bit long but packs useful instructions. Efficient overall.

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

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

No output schema, but description explains return content (markdown with exact data). Complete enough for agent to know what to expect.

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

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

Schema coverage is 100% with clear descriptions; description adds context (e.g., incidentId from list_threat_incidents) but not significantly more than schema.

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

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

Description clearly states 'Get full details of one threat-center incident' with specific content (markdown section), distinguishing it from sibling list_threat_incidents.

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

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

Explicitly says to call after list_threat_incidents, and gives detailed follow-up actions based on ecosystem (npm vs pypi) and always check_ioc_in_baseline.

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

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

No annotations are provided, so the description carries the full burden. It discloses that results are tenant-wide (across all orgs) and every result has a dashboard_url. It does not mention ordering, pagination, rate limits, or whether the tool is idempotent/safe. As a read operation, the description provides adequate but not comprehensive behavioral context.

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

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

Three sentences with no waste. The first sentence states purpose, the second defines key terms, and the third provides critical user-facing instructions. Information is front-loaded and each sentence earns its place.

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

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

Despite no output schema, the description mentions dashboard_url per detection, which is helpful. However, it does not describe the full return structure, typical fields, pagination, or ordering. For a list tool with 4 parameters and no output schema, a 3 reflects adequate but not complete guidance for an agent.

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

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

All 4 parameters have schema descriptions (100% coverage). The tool description adds value by explaining the customer fallback behavior, default status filter, and that orgScope uses an owner-scoped endpoint. This enriches the schema beyond simple type/enum definitions.

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

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

The description clearly states 'List anomalous outbound network-call detections' with a precise definition of 'anomalous' (not in Harden-Runner baseline). It distinguishes from sibling tools like list_detections, list_blocked_domain_calls, and list_suspicious_process_events by focusing specifically on anomalous network calls.

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 notes that this is 'typically the most-used detection type during an investigation,' implying primary usage. It also provides explicit instructions to include clickable dashboard_url links per detection. However, it does not explicitly compare to alternatives or state when not to use this tool.

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

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

No annotations are present, so the description carries the full burden. It reveals that the tool returns only blocked detections and mandates clickable link presentation. However, it does not disclose auth requirements, rate limits, error behavior, or the fact that results can be empty, leaving some behavioral gaps.

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

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

Two sentences with no unnecessary words. The first sentence conveys purpose and differentiation; the second provides critical output guidance. Every sentence is essential and front-loaded.

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

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

For a list tool with four well-described parameters and no output schema, the description adequately covers purpose, differentiation, and output presentation. It lacks details on error handling, sorting, and whether results are paginated, but these are reasonable omissions given the schema covers limit and status.

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, so the baseline is 3. The description adds minimal semantic value beyond the schema: it mentions the env var fallback for customer and the owner-scoped endpoint for orgScope, but these are inferred from schema. No new semantic context is provided for status or limit.

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

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

The description clearly states the tool lists blocked outbound network calls due to egress-policy enforcement, and explicitly distinguishes it from anomalous calls. This differentiates it from its sibling 'list_anomalous_network_calls', providing high specificity.

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

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

The description explains when to use this tool versus list_anomalous_network_calls by contrasting blocked vs anomalous. It also notes the requirement to present dashboard_url as clickable links, but does not provide explicit guidance on when not to use this tool or other alternatives.

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

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

No annotations; description only says 'List' (implying read-only) but omits details on pagination, rate limits, permissions, or response behavior. More context is needed for a read operation.

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

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

Two efficient sentences: first states purpose and filter criteria, second provides a concrete list of detection IDs. No 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?

Covers purpose and parameter hints well, but lacks context on default status, tenantWide scope, response structure, and behavioral details like pagination. Reasonable for a list tool but could be improved.

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 coverage, baseline is 3, but the description adds value by listing common detection IDs, enhancing understanding beyond the schema's generic description.

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

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

The description clearly states the tool lists Harden-Runner detections with filtering, and the provided common detection IDs help distinguish from more specific sibling tools like list_imposter_commit_detections.

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 general detection listing via common IDs, but lacks explicit guidance on when to use this vs. specific sibling tools like list_imposter_commit_detections.

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?

Since no annotations provided, the description fully discloses behavior: fast (one upstream call), returns calls grouped by job with step/tool attribution, includes top-level and per-job dashboard_url links. No contradictions.

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 (2-3 sentences) and well-structured, with clear sections for purpose, usage, and response details. No unnecessary words.

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

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

Despite no output schema, the description explains the response structure (grouped by job, dashboard links) and provides actionable tips (include per-job link). Given the complexity, this is fully complete for an agent to use 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?

Input schema has 100% coverage with descriptions for all three parameters. The description adds value by explaining the importance of run_id and suggesting a fallback workflow, but schema already provides the core 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 lists HTTPS calls to github.com or api.github.com from a specific workflow run, which distinguishes it from sibling tools that handle anomaly detection or general network calls.

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?

Provides explicit usage scenarios: auditing API endpoint usage, detecting unexpected writes. Also gives a prerequisite: if missing run_id, call list_recent_workflow_runs first. This guides the agent on when and how to use the tool.

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

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

Annotations are absent, so description carries full burden. It discloses that results have a dashboard_url and mandates clickable links per detection. It also explains the customer parameter fallback to env var and aggregation across all orgs. No contradiction observed.

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

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

Three sentences, front-loaded with purpose and usage context. Each sentence adds value, though the dashboard_url instruction could be embedded more succinctly. No unnecessary repetition.

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

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

No output schema exists, so description must cover return values. It mentions dashboard_url but not other fields like method, path, or timestamp. Gaps in expected output structure reduce completeness for agent 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?

Input schema has 100% coverage, so baseline is 3. Description adds context for 'customer' (fallback and aggregation) and 'orgScope' (owner-scoped endpoint), but these are already in schema descriptions. No new parameter meaning added beyond schema.

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

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

Description clearly states 'List HTTPS outbound network-call detections (TLS-intercepted calls with method + path)' which is a specific verb+resource. It distinguishes from siblings like list_anomalous_network_calls by focusing on intercepted outbound calls with method and path 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?

Provides a concrete use case: 'when you need to see WHAT an outbound call did — e.g. POSTs to a suspicious endpoint during a build'. This helps contextualize when to use this tool, but does not explicitly exclude alternatives or mention when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It describes the purpose and output feature (dashboard_url) but does not disclose any side effects, rate limits, or authentication requirements. For a read-only list tool this is adequate but not exceptional.

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

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

Two sentences: first defines purpose, second gives critical usage instruction. No unnecessary words; every sentence adds value.

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

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

Given no output schema, the description explains that each result has a dashboard_url and that they are detections of a specific security issue. It could mention additional fields or structure, but it is sufficient for an agent to understand the tool's output.

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?

Input schema has 100% description coverage, so the schema already documents each parameter well. The description adds the dashboard_url usage note but does not enhance parameter understanding beyond the schema.

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

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

The description clearly states it lists detections of a specific type (imposter commit SHA) and ties it to a security concern (Action-tampering). It is distinct from siblings like list_detections or search_action_usage by focusing on a precise indicator.

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?

Provides explicit instruction for presenting results: must include a clickable link per detection, not just the first. However, lacks guidance on when to use this tool vs. alternatives like list_detections or check_ioc_in_baseline.

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

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

With no annotations, the description carries full burden. It discloses the limit of 100 results, optional repository narrowing, and instructs to include clickable dashboard_url links per run. Missing details on authentication or rate limits, but the given behavioral details are valuable.

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

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

Two sentences, front-loaded with the core purpose, followed by usage guidance and a critical output instruction (clickable links). No filler words; every sentence earns its place.

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

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

Given no output schema, the description provides essential context: result limit, optional filtering, and the presence of dashboard_url with a usage rule. Lacks detail on other output fields or pagination behavior, but sufficient for common use cases.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that omitting 'repo' gives org-wide runs and explains the 'page' default (implied). This extra context justifies a score of 4.

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

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

The description clearly states the verb 'list', the resource 'workflow runs', and the scope '100 most recent Harden-Runner-monitored' for a GitHub organization. It distinguishes from sibling tools, which are largely security-specific list tools, by focusing on workflow runs.

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?

Provides explicit when-to-use guidance: 'Use this to discover run IDs when the user asks about a run without giving an explicit ID' with a concrete example. Lacks mention of when not to use it (e.g., if more than 100 runs needed or specific filtering), but the guidance is clear and helpful.

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?

Discloses that the API returns masked secrets (safe to display) and includes specific fields (rule_id, line_number, step_number, dashboard_url). With no annotations, this provides essential behavioral insight, though it could mention pagination or read-only nature.

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 primary purpose and followed by key behavioral and usage details. Every sentence adds value without 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?

Covers purpose, response structure, and a mandatory linking instruction. Lacks details on pagination or sorting, but for a list tool with good parameter descriptions, it is sufficiently complete.

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

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

Schema coverage is 100%, and descriptions already explain parameters well. The description adds value by detailing what the response contains, helping the agent understand the output and use parameters effectively.

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

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

The description clearly states the tool lists detections of secrets in CI build logs, specifying secret types and response fields. This distinguishes it from sibling tools like list_detections or list_imposter_commit_detections by focusing on build log secrets.

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?

Provides some usage context (secrets in CI build logs) and a mandatory linking instruction, but lacks explicit guidance on when to use this versus alternatives like list_detections, or when not to use it.

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

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

The description labels the tool as 'Read-only,' which is important but minimal. No annotations exist, so the description carries full burden; additional behavioral traits like rate limits or authentication needs are not disclosed.

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

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

Three sentences, front-loaded with key information, no unnecessary words. Every sentence adds value.

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

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

Given a simple list tool with no output schema, the description covers purpose, usage, and read-only nature. Could mention response format, but not essential.

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% for the single optional parameter, and the description does not add further semantic value beyond the schema. 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?

Description clearly states the verb 'list' and resource 'suppression (detection) rules' with tenant scope. This distinguishes it from sibling tools like create_suppression_rule or delete_suppression_rule.

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

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

Explicitly advises using the tool before creating a new rule to check for duplicates or near-overlaps, providing clear context. However, it does not mention when not to use or suggest alternatives.

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

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

No annotations provided, so description carries full burden. It discloses that it's a virtual detection ID aggregating three types and that results have a dashboard_url. Lacks explicit statement on read-only nature or mutability. Adequate but not rich.

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

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

Two sentences, front-loaded with purpose and additional detail. Efficient, but the second sentence could be split for clarity. Every sentence earns its place.

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

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

Given no output schema, description explains dashboard_url but not other return fields. Parameter descriptions are thorough. Usage guidance is clear. Some room for improvement in specifying return structure.

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 has 100% coverage with descriptions for all 4 parameters. Description adds extra meaning: explains the virtual detection ID aggregation and instructs to present clickable links per detection, adding value beyond schema.

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

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

Describes a specific verb (list) and resource (suspicious-process-event detections), explains it's a virtual detection ID aggregating three real types, and distinguishes from siblings like list_detections and list_imposter_commit_detections.

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?

States explicit usage context: 'Use for runtime-evidence of compromise during an incident.' However, does not explicitly mention when not to use this tool versus alternatives (e.g., list_detections), but provides clear context for use.

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

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

No annotations provided, so the description carries full burden. It implies read-only behavior by listing data, and explains parameter fallback. Could mention rate limits or data freshness, but overall clear about non-destructive nature.

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?

Four sentences, each serving a purpose: purpose, usage guidance, result feature (dashboard_url), and parameter explanation. No fluff.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, usage sequence, and result handling. No 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 coverage is 100% and the description repeats the same information about the 'customer' parameter being optional with fallback to env var. No additional meaning beyond the schema.

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

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

The description states 'List every GitHub organization installed under a StepSecurity tenant,' which is a specific verb and resource. It clearly distinguishes from sibling tools that focus on processes, detections, or endpoints.

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

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

Explicitly tells when to use the tool ('Call this first when a user asks for a tenant-wide view') and directs to subsequent tools like 'find_repos_using_endpoint' for per-org operations. Provides actionable advice about the dashboard_url.

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

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

No annotations are provided, so the description carries the burden. It states the return format is a 'compact summary (no markdown body)' and implies a read-only operation by advising to get full details via another tool. Could be improved by explicitly stating it is non-destructive, but the context strongly suggests a safe query.

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

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

Three dense sentences with no wasted words. Front-loaded with purpose, followed by usage directive, then return format and next step. Every sentence serves a distinct function.

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 single required parameter, no output schema, and the context of sibling tools, the description fully covers what the tool does, when to use it, what it returns, and how to proceed. No obvious 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 coverage is 100% (1 param described). The description's mention of 'for a GitHub organization' merely paraphrases the schema's description. No additional parameter semantics beyond what the schema already provides, 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?

Clearly states the verb 'List' and the resource 'supply-chain threat-center incidents' scoped to a GitHub organization. Differentiates from sibling tools like get_threat_incident by positioning it as the initial lookup step.

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

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

Provides explicit when-to-use guidance: 'ALWAYS call this first when the user mentions a known supply-chain incident...' with concrete examples (e.g., 'axios compromise'). Also instructs to call get_threat_incident afterward. No ambiguity about 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?

No annotations are provided, but the description correctly discloses the tool returns 'pong'. For a simple ping, this is sufficient behavioral transparency with no contradictions.

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

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

A single sentence that is concise and front-loaded with the key behavior ('Returns pong') followed by usage context. No wasted words.

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

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

Given the low complexity, high schema coverage, and absence of an output schema, the description fully covers what the agent needs: return value and use case.

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

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

Schema coverage is 100% and the description adds no additional meaning beyond what the schema already provides ('Optional echo payload'). 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 returns 'pong' and its purpose is to verify server reachability, which is distinct from all sibling tools that involve security analysis.

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 says to use it 'to verify the MCP server is reachable', providing clear context. While no exclusions or alternatives are given, none are needed for a simple health check.

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?

Discloses it is approximate, client-side, and explains matching logic differences (exact/wildcard vs CIDR/regex). No annotations provided, so description fully carries the behavioral transparency burden.

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

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

Concise, front-loaded with core purpose, each sentence adds value: preview action, output description, usage timing, and matching approximation note.

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?

Describes output (count and up to 20 samples with dashboard_url) despite no output schema. Covers approximation and matching differences. Complete for a preview tool.

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

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

Schema coverage is 100%, but description adds context by explaining detectionId as detection type and conditions as match keys with examples. Provides meaning beyond schema alone.

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?

Description clearly states it is a client-side preview of suppression rule impact, fetches recent detections, filters conditions, returns count and samples. Distinguishes from create_suppression_rule by advising use before creation.

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

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

Explicitly states to use this tool before create_suppression_rule to show concrete impact. Also warns that preview matching is approximate and server matching may differ, guiding proper usage.

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

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

With no annotations, the description carries full burden. It explains the output (one entry per workflow) but does not disclose behavioral traits like authorization requirements, rate limits, or handling of missing actions. It adds some value beyond the schema but lacks depth.

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

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

Two sentences, no fluff. Directly states purpose, gives an example, and specifies output format. Every sentence earns its place.

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

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

Given the simplicity (2 string params, no output schema), the description is nearly complete. It mentions the return format and a use case. Missing details like error handling or pagination, but overall sufficient for the complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces that 'action' should be in 'owner/repo' form without tag/sha, but adds no significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find which workflows across the organization use a given GitHub Action.' It provides a concrete example ('which repos use aquasecurity/setup-trivy?') and specifies the output format, distinguishing it from sibling tools.

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

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

The description implies usage context with the example 'responding to a compromised Action,' but does not explicitly state when to use or avoid this tool compared to siblings. No alternatives or exclusion criteria are mentioned.

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

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

No annotations provided; description highlights write operation and safety check, but lacks details on error behavior, idempotency, or permission requirements for a mutation tool.

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

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

Single, clear sentence that immediately conveys purpose and critical requirement (confirm). Front-loaded and 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?

Lacks details on conditions object format, error handling, return value, and prerequisites. Given no output schema and complexity, the description is incomplete for reliable invocation.

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

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

Schema coverage is 50%; description adds minimal value beyond schema. It lists fields but does not explain conditions structure or provide extra semantics for undocumented parameters.

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?

Clearly states verb 'update' and resource 'suppression rule', and lists updatable fields (name, description, conditions). Distinguishes from siblings like create and delete.

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?

Specifies that it requires 'confirm: true' and is a WRITE OPERATION, implying user approval needed. No explicit when-not-to-use or alternative tools mentioned, but context is adequate.

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