Ausstehende Kommentare zählen

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

With no annotations, the description carries full responsibility for disclosing behavior. It merely states 'counts comments by status' without specifying return format (e.g., a single number, an array of per-status counts), whether it operates on all comments or only, and lacks any details about filtering logic or response fields. This is insufficient for an agent to predict tool 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 a single short sentence, but it is under-specified rather than concise. It lacks essential details about what the count represents and the response structure. The brevity does not serve the agent's needs, making it more of a placeholder than a valuable specification.

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 tool with no parameters, no output schema, and no annotations, the description should fully clarify the tool's purpose and return value. It does neither, leaving the agent to guess whether it returns a simple integer, a status-wise breakdown, or something else. The lack of clarity makes the tool effectively unusable without external documentation.

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 tool has zero parameters, so the baseline is 4. However, the description's mention of 'by status' implicitly references a status filter that is not exposed as a parameter, causing confusion about how the status is determined. Since the description adds no meaningful parameter information and actively introduces ambiguity, it is slightly below the baseline.

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 'Zählt Kommentare nach Status' (Counts comments by status) is vague and misaligned with the tool name and title, which specifically indicate counting pending comments. It does not clearly state that it returns a count of pending/unapproved comments, and the phrase 'by status' introduces ambiguity about grouping or filtering by multiple statuses. The verb and resource are present, but the scope is unclear and inconsistent with the intended purpose.

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?

There is no guidance on when to use this tool versus alternatives like comment_list or comment_get. The description does not mention use cases, prerequisites, or exclusions. An agent has no basis to decide when to invoke this tool instead of sibling tools.

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