Skip to main content
Glama
Sign In
vivac

vivac

by JAAvila-Of
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Why a node exists

vivac_why
Read-only

Read a node's goal-to-node path, parallel work, blockers, and recent notes to understand why the work exists and what dependencies affect it.

Instructions

Read a node, its goal-to-node path, parallel work and blockers. Default caps open children/siblings at eight each, retaining blockers; newest three notes are whole, earlier notes counted. full includes all and historical anchors/governance. Use only for later siblings to avoid repeating their shared path.

Input Schema

NameRequiredDescriptionDefault
idYesNode ID or alias, e.g. t4.
fullNoAll open branches and historical anchors/governance; conflicts with project.
onlyNoOnly this node; avoid repeating shared lineage when reading siblings.
projectNoProject name from everywhere results; conflicts with full.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.22.1
    • changedInput schema / properties / full / description
      Previous value: -"Every sibling and every child still open, not only the eight the answer keeps, plus each step's anchor, standing decisions and what was open at the time: what vivac why --full prints. Refused together with project."New value: +"All open branches and historical anchors/governance; conflicts with project."
    • changedInput schema / properties / id / description
      Previous value: -"The node as the tree names it: g1, t12, f74, d29."New value: +"Node ID or alias, e.g. t4."
    • changedInput schema / properties / only / description
      Previous value: -"The node alone: no path, no siblings, no children. For the next sibling once one why has already brought the path they share."New value: +"Only this node; avoid repeating shared lineage when reading siblings."
    • changedInput schema / properties / project / description
      Previous value: -"Opens a node that lives in another tree: a project name from `vivac_find`'s `everywhere`, since an alias only means something inside its own tree."New value: +"Project name from everywhere results; conflicts with full."
  2. Changed1 schema field changedv0.17.12
    • addedInput schema / properties / only
      Added value: +{
+  "description": "The node alone: no path, no siblings, no children. For the next sibling once one why has already brought the path they share.",
+  "type": "boolean"
+}
  3. First observedv0.17.1

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already establish that this is a safe, read-only, closed-world operation, so the safety profile needs no restating. The description instead discloses real behavioral traits: default caps of eight open children and siblings, blockers retained despite the cap, the newest three notes returned whole with earlier ones only counted, and `full` pulling in historical anchors and governance. That truncation semantics is exactly the kind of context an agent cannot get from annotations or schema, though it doesn't say how counts are surfaced in the output.

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?

Three sentences, front-loaded with what is read, then the default truncation behavior, then the modifier flags. Every sentence carries information. Minor cost: compressed phrasing like 'newest three notes are whole, earlier notes counted' takes a beat to parse.

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

Completeness4/5

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

With no output schema, the description must convey what comes back, and it does: node, path, parallel work, blockers, notes, and optionally anchors and governance. It also explains the truncation rules that govern result size. What's missing is any sense of ordering or shape of the returned content, but for a read-only tool with full annotation coverage this is close to sufficient.

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 coverage is 100%, so all four parameters are already documented, and the description largely echoes those definitions — `full` including history, `only` avoiding repeated lineage. The one addition is the explicit note that `full` and `project` conflict, which is already present in the schema. Baseline 3 applies when the schema carries the parameter burden.

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

Purpose4/5

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

The description uses a specific verb ('Read') and enumerates the resource set returned: the node, its goal-to-node path, parallel work, and blockers. That is far more concrete than the title's 'Why a node exists'. It stops short of differentiating itself from siblings like vivac_open or vivac_find, so an agent cannot tell from the text alone which read tool to pick.

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

Usage Guidelines3/5

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

There is one piece of genuine routing advice: use `only` for later siblings to avoid repeating their shared path. But that is guidance on parameter choice, not on when to call vivac_why versus vivac_open or vivac_brief. Usage is implied by the returned content rather than stated.

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