Skip to main content
Glama

list_categories

Lists document categories with live document counts so you can choose valid category filters before searching or listing documents.

Instructions

List all document categories with their document counts.

Read-only. No side effects. Reflects the live index state.

Returns: JSON string with category names, document counts per category, and total document count.

Usage: Use before filtering search_knowledge() or list_documents() by category to see which categories exist and how many documents each contains; search_knowledge() still rejects a listed name that is not configured, such as one stored by add_document(). Use get_index_stats() instead for broader system health metrics (model name, cache hit rate, BM25 status).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_categories"
  }
}

Input Schema

NameRequiredDescriptionDefault

No arguments

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv3.0.0

TDQS

A4.8/5.0
Behavior5/5

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

No annotations are supplied, so the description carries the full burden, and it does: 'Read-only. No side effects.' declares the safety profile, and 'Reflects the live index state' declares freshness. The caveat that listed names may not be configured in search_knowledge reveals a non-obvious behavioral interaction between tools that no structured field conveys.

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

Conciseness4/5

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

Labelled sections (Returns, Usage) make it scannable and front-load the purpose before the caveats. The 'Returns: JSON string with category names...' block partly restates what the output schema already provides, which is the one piece of mild redundancy.

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

Completeness5/5

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

For a zero-parameter read tool with an output schema, everything an agent needs is present: purpose, safety profile, freshness, the return payload, and routing to the correct sibling. Nothing material is missing.

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

Parameters4/5

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The empty schema is fully consistent with the description's framing as a global, unfiltered listing.

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

Purpose5/5

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

The opening sentence states a specific verb and resource ('List all document categories') plus the payload ('with their document counts'), so an agent knows exactly what comes back without opening the schema. It is clearly separable from siblings like list_documents and get_index_stats, which the usage section reinforces.

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

Usage Guidelines5/5

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

It names the exact downstream calls this enables (search_knowledge, list_documents filtering) and gives an explicit alternative with its selection condition: 'Use get_index_stats() instead for broader system health metrics (model name, cache hit rate, BM25 status).' It even warns that a listed category may still be rejected by search_knowledge if it came from add_document, which is precisely the kind of when-not guidance that prevents wasted calls.

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