Skip to main content
Glama
Sign In
ctxvault

ctxvault

by Filippo-Venturini
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

list_entities

Enumerate every entity in an episodic vault with mention counts to discover subjects and recorded names before querying; optionally include closed entities.

Instructions

List the entities an episodic vault knows about, with how many episodes mention each one. This is the vault's vocabulary: use it to find out what subjects exist before querying for them, to spot the name a person or thing is recorded under, or to see what has gone quiet. Unlike query_episodes it enumerates rather than ranks, so nothing is left out. By default only entities named by statements that still hold are listed; pass include_closed to see everything the vault ever recorded.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "vault_name": "<vault_name>"
    },
    "name": "list_entities"
  }
}

Input Schema

NameRequiredDescriptionDefault
valid_atNo
vault_nameYes
min_episodesNo
include_closedNo

Output Schema

NameRequiredDescriptionDefault
totalYes
entitiesYes
vault_nameYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.9.1

TDQS

A4.3/5.0
Behavior4/5

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

No annotations exist, so the description carries the full burden, and it does disclose the key behavioral trait: by default only entities named by statements that still hold are listed, with include_closed needed to see everything ever recorded. That default-filter behavior is non-obvious and important. It does not mention volume/pagination or any access constraints, which keeps it short of a 5.

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

Conciseness5/5

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

Four sentences, each doing distinct work: purpose, return content, use cases, sibling contrast, and default-filter caveat. It is front-loaded with the core function and contains no filler or restatement of the name.

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

Completeness3/5

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 default-versus-include_closed behavior is covered. However, with 4 parameters at 0% schema coverage, the undefined semantics of valid_at and min_episodes leave an agent guessing about time-scoping and filtering.

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

Parameters3/5

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, and it only partially does: include_closed is explained clearly and min_episodes is obliquely implied by 'how many episodes mention each one'. Two parameters, valid_at and min_episodes, receive no explanation of their meaning or effect on results.

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?

States a specific verb and resource ('List the entities an episodic vault knows about') and adds what is returned ('how many episodes mention each one'). It also contrasts itself with the sibling query_episodes ('enumerates rather than ranks'), so the agent can distinguish the two without opening either schema.

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?

Gives three concrete when-to-use cases: discovering which subjects exist before querying, resolving the recorded name of a person or thing, and spotting entities that have gone quiet. It names the alternative tool and the condition that selects this one ('enumerates rather than ranks'), leaving little to inference.

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

Deploy Server

Other Tools