github_list_discussions

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

With no annotations, the description carries the full burden and does disclose significant behavior: default repository, default ordering by UPDATED_AT descending, cursor pagination with 'after'/'before', switch to server-side full-text search when query/category_name are supplied, and that category_name is a GitHub qualifier rather than a client-side filter. It stops short of stating read-only safety, authentication needs, rate limits, or error behavior.

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

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

Two dense, front-loaded sentences with no filler: the default scope is stated first, then the no-query mode, then the query-mode behavior and its pagination caveat. Every clause carries operational information.

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 described, and the description covers the default repo, both modes, ordering, and pagination differences. The main remaining gap is the undocumented 'limit' parameter and missing read-only/auth context, but the definition is largely sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate; it adds meaning for after/before (cursor pagination), query (triggers full-text search mode), category_name (GitHub qualifier semantics), and repo_full_name (default value). The 'limit' parameter is left entirely undocumented, which is a real gap given zero 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 states a specific verb and resource ('Elenca le GitHub Discussions di un repository') and names the default repository, so an agent knows exactly what it returns. It is distinguishable from siblings like github_get_discussion and github_list_discussion_categories, though it never explicitly contrasts itself with them.

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?

It explains the two invocation modes (no query/category vs query/category_name) and their differing sort and pagination behavior, which is useful context. But it gives no explicit when-to-use versus alternatives such as github_get_discussion or github_list_discussion_categories, leaving selection to inference.

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