Skip to main content
Glama
Sign In
CPersona

CPersona

Official
by Cloto-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

traverse

Read-only

The neighbourhood of a declared entity, as a graph: the entity named, its aliases, the entity -> entity relations declared on it and on what they reach, up to max_hops in either direction, and the refs of the records that mention each…

Instructions

The neighbourhood of a declared entity, as a graph: the entity named, its aliases, the entity -> entity relations declared on it and on what they reach, up to max_hops in either direction, and the refs of the records that mention each entity. Only what was declared (declare_associations, or associations on store); nothing is inferred. No record text: expand a ref with get_contents. entity is a name or an alias, compared after normalization; when it names more than one entity this call can read (a project's and the global pool's), all are starts. ORDER: entities by hops, then by the most recently declared relation that reached them, then by id; mentions by record id; relations most recently declared first. limit bounds both the entities returned and the refs listed per entity. Response: {entity, max_hops, limit, entities:[{id, name, hops, aliases?, mentions?, mentions_omitted?}], relations:[{id, subject, predicate, object, declared_by, declared_at, anchor_ref?}] (subject/object are entity ids from entities; a relation is listed when both ends are), entities_omitted?, bounds?:{omitted:[max_hops | limit]}, reason?:'no_such_entity'}. Relation ids are what declare_associations' retract takes. Records are listed only when this call could read them: the project, channel and source_id filters apply as in recall.

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": {
      "agent_id": "<agent_id>",
      "entity": "<entity>"
    },
    "name": "traverse"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum entities returned, and maximum mentioning refs listed per entity.
entityYesA declared entity name or alias.
channelNoMemory channel filter -- same semantics as in `recall`.
agent_idYesAgent identifier
max_hopsNoRelations to follow from the entity, in either direction. 0 returns the entity alone.
source_idNoPer-user source filter on the mentioning records -- same semantics as in `recall`.
project_idNoγ filter -- same semantics as in `recall`. v2.5.1: pass '@auto' to resolve this agent's default from the server's operating context, echoed as resolved_project_id. An unmapped agent gets '' with operating_context_warning; enforce='off' omits the warning, and enforce='reject' refuses a write. bug-186: resolution requires a configured operating context. With none (the default, or an unparsable sidecar) '@auto' is NOT resolved: it is stored and filtered as a literal project_id, resolved_project_id echoes '@auto', and no warning is raised. Check resolved_project_id before relying on it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.6.12
    • changedInput schema / properties / project_id / description
      Previous value: -"γ filter -- same semantics as in `recall`. v2.5.1: pass '@auto' to resolve this agent's default from the server's operating context (the resolution is echoed as resolved_project_id; an unmapped agent yields operating_context_warning). bug-186: resolution requires a configured operating context. With none — the default, and equally the outcome of a sidecar that fails to parse — the sentinel is NOT resolved: it is stored and filtered as the literal project_id '@auto', resolved_project_id echoes '@auto', and no warning is raised. Read resolved_project_id before relying on the resolution."New value: +"γ filter -- same semantics as in `recall`. v2.5.1: pass '@auto' to resolve this agent's default from the server's operating context, echoed as resolved_project_id. An unmapped agent gets '' with operating_context_warning; enforce='off' omits the warning, and enforce='reject' refuses a write. bug-186: resolution requires a configured operating context. With none (the default, or an unparsable sidecar) '@auto' is NOT resolved: it is stored and filtered as a literal project_id, resolved_project_id echoes '@auto', and no warning is raised. Check resolved_project_id before relying on it."
  2. Addedv2.5.12

TDQS

A4.6/5.0
Behavior5/5

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

Consistent with readOnlyHint=true. Beyond the annotation it discloses that nothing is inferred, that no record text is returned, the exact ordering rules (hops, then most recently declared relation, then id; mentions by record id; relations newest first), how `limit` is applied at two levels, the visibility constraint on records, the omission/bounds signaling, and the 'no_such_entity' reason. It also notes relation ids are the tokens `declare_associations.retract` consumes, which is genuinely non-obvious behavior.

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?

It is front-loaded with purpose and scope before detail, and every clause carries information: ordering, bounds, error reason, visibility. The trade-off is a dense single block with the response shape enumerated inline; in the absence of an output schema this earns its place, but paragraph or bullet structure would improve scanability.

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 7-parameter graph tool with no output schema, the description fully specifies the return shape (entity, max_hops, limit, entities[], relations[], omission fields, bounds, reason), ordering, truncation behavior, and visibility filtering. Nothing an agent needs in order to call and interpret it 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?

With 100% schema coverage the baseline is 3, and the description adds real meaning beyond the schema: `entity` is normalized and matched against aliases, and when it resolves to an entity in both a project and the global pool, all matches are traversal starts. It also clarifies `limit` bounds both entity count and per-entity ref count. `max_hops` bi-directionality and the filter semantics largely restate the schema.

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 description opens with a precise statement of the resource and scope: the declared entity's neighbourhood as a graph, including aliases, entity→entity relations up to `max_hops` in either direction, and refs of mentioning records. It explicitly separates itself from siblings by stating there is no record text and pointing to get_contents for expansion. An agent can distinguish this from `recall` or `declare_associations` without opening a schema.

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

Usage Guidelines4/5

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

It defines the data's provenance ('Only what was declared (declare_associations, or `associations` on store); nothing is inferred') and routes the agent to `get_contents` when record text is needed. It also explains that the project/channel/source_id filters behave as in `recall`. It stops short of explicitly saying when to prefer this over `recall`/`recall_with_context` for non-graph lookups, so it is clear but not a full when/when-not map.

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