Skip to main content
Glama
Sign In
vivac

vivac

by JAAvila-Of
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

File a node without moving the focus

vivac_add

Creates a typed node—such as a finding, task, decision, constraint or rule—in the provenance tree without changing focus, letting you record work or branches under the current context.

Instructions

File a typed node without changing focus: findings, pending work or a branch of existing work. Search first; never duplicate. Findings are recorded when reported, one per finding; close records immediately with vivac_done and a Record: outcome. Use push for work starting now, decide for choices, constraint for continuing norms (root if global), and rule for requirements checked by a command or human judgement.

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": {
      "title": "<title>"
    },
    "name": "vivac_add"
  }
}

Input Schema

NameRequiredDescriptionDefault
armNoRule verification commands, all run in arm_dir; omitted means judged. Vivac never runs them.
refNoPaths or identifiers this node is about.
whyNoWhy this matters.
rootNoCreate at root instead of under focus; conflicts with parent.
typeNogoal, task, decision, question, constraint, finding, assumption, pillar or rule. Default task under focus, goal at root. User norms: constraint (root if global); rule: pillar criterion, read via vivac_rules; pillar: name and what it rejects.
titleYesTitle words, never an ID; parent ID goes in parent.
blocksNoParent cannot close until this node closes.
parentNoParent node ID/alias; defaults to focus, else root. Conflicts with root.
againstNoDecision only: one pillar/rule plus compliance sentence per item, e.g. "r12: writes stay local". Not constraints.
arm_dirNoExisting working directory relative to the tree root; required with arm.
governsNoFile globs governed by this work or norm.
supersedesNoRetire an in-force decision/constraint/rule/pillar, preserving history. New node must be one of those kinds; use the correct kind for a misclassified norm.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv0.22.1
    • changedInput schema / properties / against / description
      Previous value: -"Only for a decision: a pillar or rule it was judged against and a sentence on how it holds, as one entry: \"r12: the write path stays local\". Repeat for each one."New value: +"Decision only: one pillar/rule plus compliance sentence per item, e.g. \"r12: writes stay local\". Not constraints."
    • changedInput schema / properties / arm / description
      Previous value: -"Commands that verify this rule, one per entry, all run in arm_dir. Only for a rule; a rule without one is judged. vivac never runs them."New value: +"Rule verification commands, all run in arm_dir; omitted means judged. Vivac never runs them."
    • changedInput schema / properties / arm_dir / description
      Previous value: -"The folder every arm given here runs in, relative to the folder that holds .vivac: vivac, say, or . for that folder itself. Required with arm, refused without it. It has to exist."New value: +"Existing working directory relative to the tree root; required with arm."
    • changedInput schema / properties / blocks / description
      Previous value: -"Its parent cannot close while this one is still open."New value: +"Parent cannot close until this node closes."
    • changedInput schema / properties / governs / description
      Previous value: -"Globs of files this node's work is expected to touch."New value: +"File globs governed by this work or norm."
    • changedInput schema / properties / parent / description
      Previous value: -"The node it hangs from. Defaults to the current focus, or the root if there is none."New value: +"Parent node ID/alias; defaults to focus, else root. Conflicts with root."
    • changedInput schema / properties / root / description
      Previous value: -"Born at the root, with no parent, instead of under the focus. Refused together with parent."New value: +"Create at root instead of under focus; conflicts with parent."
    • changedInput schema / properties / supersedes / description
      Previous value: -"An earlier decision, constraint, rule or pillar this one replaces, while it is still in force: it becomes superseded and keeps its history. For a node filed with the wrong type, write the one it should have been and name the old one here. This node has to be one of those four types too."New value: +"Retire an in-force decision/constraint/rule/pillar, preserving history. New node must be one of those kinds; use the correct kind for a misclassified norm."
    • changedInput schema / properties / title / description
      Previous value: -"What this node is, in a few words."New value: +"Title words, never an ID; parent ID goes in parent."
    • changedInput schema / properties / type / description
      Previous value: -"goal, task, decision, question, constraint, finding, assumption, pillar or rule. Defaults to goal at the root, task otherwise. A norm the person sets for the work from now on is a constraint, with root when it holds for all work, so every brief shows it. A rule is a line a pillar draws, read with vivac_rules when work is checked. A pillar is titled with its name and what it restricts, in the project's own words."New value: +"goal, task, decision, question, constraint, finding, assumption, pillar or rule. Default task under focus, goal at root. User norms: constraint (root if global); rule: pillar criterion, read via vivac_rules; pillar: name and what it rejects."
  2. Changed2 schema fields changedv0.18.0
    • addedInput schema / properties / supersedes
      Added value: +{
+  "description": "An earlier decision, constraint, rule or pillar this one replaces, while it is still in force: it becomes superseded and keeps its history. For a node filed with the wrong type, write the one it should have been and name the old one here. This node has to be one of those four types too.",
+  "type": "string"
+}
    • changedInput schema / properties / type / description
      Previous value: -"goal, task, decision, question, constraint, finding, assumption, pillar or rule. Defaults to goal at the root, task otherwise. A pillar is titled with its name and what it restricts, in the project's own words."New value: +"goal, task, decision, question, constraint, finding, assumption, pillar or rule. Defaults to goal at the root, task otherwise. A norm the person sets for the work from now on is a constraint, with root when it holds for all work, so every brief shows it. A rule is a line a pillar draws, read with vivac_rules when work is checked. A pillar is titled with its name and what it restricts, in the project's own words."
  3. First observedv0.17.1

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is given. The description adds genuinely useful behavior beyond that: focus is untouched, the node is not auto-closed, and closure requires a separate vivac_done call with a 'Record: outcome'. It says nothing about what happens on a duplicate title despite the 'never duplicate' warning, and nothing about what the call returns (a new ID/alias), which matters given idempotentHint=false.

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?

The purpose and the non-focus guarantee are front-loaded, and the second sentence packs the routing table into one line without filler. It is dense to the point of being terse (semicolon-chained clauses, undefined shorthand like 'Record: outcome'), but no sentence is wasted.

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?

For a 12-parameter creation tool with 100% schema coverage and full annotations, the description covers purpose, kind selection, deduplication, and the follow-up closure workflow. The notable remaining gap is return behavior — the agent is told to 'search first' and pass a 'parent' ID, but not that this call yields a node ID/alias it will need for vivac_done, and there is no output schema to fall back on.

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 100%, so the baseline is 3; the schema already documents arm, against, governs, supersedes, root/parent conflict, and type values in detail. The description adds some routing value by implying which kind to pick for each situation, but it does not clarify nullable quirks such as arm_dir being required with arm or the parent/root exclusivity beyond what the schema states. Net: schema does the heavy lifting, description adds only marginal meaning.

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 opens with a specific verb+resource: 'File a typed node without changing focus', then enumerates the kinds ('findings, pending work or a branch of existing work'). The 'without changing focus' qualifier is the key differentiator from siblings like vivac_push/vivac_open. It stops short of contrasting itself against all 17 siblings (e.g. vivac_note, vivac_park, vivac_declare), which are plausibly ambiguous with this tool.

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 gives real routing rules: 'Use push for work starting now, decide for choices, constraint for continuing norms (root if global), and rule for requirements checked by a command or human judgement', plus a lifecycle rule ('close records immediately with vivac_done and a Record: outcome'). It also sets a precondition ('Search first; never duplicate'). What's missing is explicit when-not-to-use guidance against the near-synonym siblings (note, park, declare), which would make routing unambiguous.

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