github_list_secret_scanning_alerts

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with them — 'effect: Required and must be read; Spring verifies it' reinforces the read-only profile. The description adds the routing restriction and the meaning of idempotency_key, which is modest value beyond annotations. However, it does not describe operational behavior (e.g., what alerts are returned, pagination, or GitHub organization/repo scoping), and the generic line about approval_ref 'when resuming a write' leaks template text that is mildly confusing for a read-only tool.

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

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

The description is compact and organized as a header, one constraint line, and a parameter list — a reasonable structure. But the opening line repeats the name twice ('Github connector operation list_secret_scanning_alerts (platform tool github.list_secret_scanning_alerts)') with no added information, and several parameter glosses are generic boilerplate that could apply to any connector tool.

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?

An output schema exists, so return values need not be documented. But for correct invocation, an agent needs to know what to place in the arguments JSON string — the GitHub-specific inputs for listing secret scanning alerts (repository, owner, state, resolution, etc.) — and that information is entirely absent. With no nested object schema and no argument documentation, the description leaves the critical input unspecified, making correct invocation underdetermined.

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

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

Schema description coverage is 0%, so the description bears the full burden and does provide a one-line gloss for each of the 7 scaffolding parameters (project_id, project_ref, connector_account_ref, etc.). However, the most important parameter, arguments, is glossed only as 'JSON string of arguments for the connector operation' with zero detail about the actual GitHub payload structure (owner, repo, state, secret_type, etc.). The agent gets wrapper semantics but not the operation semantics needed to construct a valid call.

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 first sentence merely restates the name: 'Github connector operation list_secret_scanning_alerts' is tautological. The description never states that this tool lists GitHub secret-scanning alerts, what such alerts are, or how this differs from the closely named siblings github_list_code_scanning_alerts and github_list_dependabot_alerts. An agent selecting among these cannot tell them apart from the description alone.

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 when-to-use or when-not-to-use guidance is provided, and no alternatives are named. The only usage-adjacent statement, 'Routes only through the exact project/account governed connector authority,' is a routing constraint rather than a decision rule. The description does not explain how to choose this over github_list_code_scanning_alerts or github_list_dependabot_alerts.

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