list_facets

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

With no annotations, the description carries the full burden, and it does disclose one real behavioral trait: results exclude closed statements by default. It says nothing about whether counts are computed across a large dataset, whether they are exact or approximate, or what the response looks like.

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?

One sentence with the purpose front-loaded and the filter caveat trailing as a parenthetical. Nothing is wasted, though the telegraphic style ('Counts of problem statements per...') costs a little readability.

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?

With one optional boolean, no annotations, and no output schema, the description is close to sufficient: it names what is counted and the three grouping dimensions. It stops short of clarifying whether the three dimensions are separate facet lists or a cross-tabulation, which matters for interpreting results.

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 carry the single parameter, and it does explain that include_closed widens the default open-only scope. It remains ambiguous whether closed items are merged into the counts or reported separately, so the semantics are only partially clarified.

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?

States a specific operation (counting problem statements) and the grouping dimensions (organization, category, theme), which distinguishes it from the retrieval siblings search_problem_statements and get_problem_statement. It never names an alternative explicitly, so the differentiation is inferred rather than stated.

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 parenthetical 'open ones only unless include_closed' implies the intended default view and when to flip it, but there is no explicit guidance on when to use this aggregation tool versus search_problem_statements for browsing statements. Usage is only implied.

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