vivac

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

Annotations disclose the safety profile (write, non-destructive, non-idempotent), so the description's job is to add context. It does: dedup constraint via vivac_find, the one-node-per-finding rule written when the person is told, and the record-closing workflow. It does not explicitly warn that a repeated call creates a duplicate node, but the dedup guidance and idempotentHint=false together convey that.

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

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

The core distinction from vivac_push is front-loaded in the first sentence and there is no filler per se, but the description is dense and runs long with several trailing workflow rules that could be tightened. Appropriately sized for an 11-parameter tool, though not maximally lean.

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

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

No output schema exists and 11 params (1 required) give this tool real complexity, but the description covers the primary use cases, the dedup prerequisite, sibling routing, and node-creation semantics. It does not explain return values or what filing produces, which is the remaining gap.

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

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

Schema description coverage is 100% across all 11 parameters, so the schema already documents every field including type, arm, ref, why, parent and governs. The description adds meaning for the 'finding' and record node concepts but no per-parameter syntax or format. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and effect ('File a node without touching the stack: the focus stays exactly where it was') and explicitly contrasts with the sibling vivac_push ('is for what comes next; this is for what was just noticed'). An agent can distinguish it from vivac_push, vivac_find, and vivac_done without opening any schema.

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

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

Gives explicit when-to-use cases ('a finding surfaced while working on something else, a sibling task filed for later'), names the alternative it is not (vivac_push), prescribes a prerequisite ('Look first with vivac_find: what the tree already holds is not filed twice'), and routes follow-up work to vivac_done for records. Nothing about selection is left to inference.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real value beyond that by disclosing that vivac never executes the command ('it hands it to whoever checks the rule') — a genuinely useful behavioral fact. It stops short of explaining duplicate/idempotency behavior despite 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.

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

Front-loads the core action and the off-mode in the first sentence, then adds rationale. The closing clause about 'the day a rule became checkable is part of its history' is poetic and arguably speaking to motivation rather than mechanics, but it is short and does orient the agent's intent.

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

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

For a write tool with 100% schema coverage and no output schema, the description covers the add/remove duality and the non-execution behavior adequately. It leaves minor gaps around what happens on repeated calls (idempotentHint=false), but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents id, dir, command, and off. The description's mention of the 'off' removal mode and the 'folder it runs in' only restates what the schema provides, adding no new syntax or format detail. Baseline 3 is correct.

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

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

States a specific verb (record) and resource (a command that verifies a rule plus its folder), and explicitly covers the inverse mode ('or with off, remove one'). This is clearly distinguishable from 'declare a rule' or 'note something' siblings like vivac_declare/vivac_note.

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

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

Gives an explicit timing trigger: 'Call it the moment a test for a rule exists.' That is actionable context for when to invoke it. However, it never names an alternative tool or a when-not-to-use condition, so the sibling-routing guidance is incomplete.

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

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

Annotations already establish read-only, non-destructive, closed-world behavior, and the description usefully goes beyond them by detailing the readout's contents (focus, parked nodes, decisions, last safe point). Since no output schema exists, this enumeration is the agent's only signal about what comes back, and it covers that burden well.

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

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

The core sentence front-loads the purpose ("Where you are ... and what NOT to touch") and the trailing sentence lands the usage instruction. It is dense but every clause maps to a distinct part of the returned brief; slightly long but not padded.

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

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

With no parameters and no output schema, the description carries the return-value burden alone, and it does so by listing the four components of the brief. That is sufficient for an agent to call and interpret it, though the absence of any format or size cue leaves a minor gap.

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

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

This is a zero-parameter tool, so there is nothing for the description to disambiguate and the baseline is 4. The description adds no misleading parameter claims.

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

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

The description names a concrete deliverable – a session brief – and enumerates its parts: focus with lineage, parked nodes with reasons, governing decisions, and the last safe point. An agent immediately understands it returns a synthesized state view rather than a filtered query. It does not explicitly contrast itself with siblings like vivac_why or vivac_find, so it stops short of a 5.

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

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

"Read it before anything else when a session opens" is an explicit, actionable usage directive that tells the agent exactly when to reach for this tool. It gives no exclusions or named alternatives, so an agent must still infer why it would choose vivac_why or vivac_find at other moments.

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

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

Annotations cover only the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), consistent with a write tool. The description adds behavior not in the annotations: vivac validates that each named pillar/rule 'exists and still governs' while the accompanying sentence is not judged — useful validation semantics for the `against` field. It does not discuss what happens on supersession or duplicate titles, so it isn't exhaustive.

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

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

Three sentences, front-loaded with the core action and timing rule, with the rationale ('proposed again in a month') following rather than leading. The closing line — 'a pillar judged in silence reads the same as one skipped' — is rhetorical but earns its place as a memorable rule of thumb; the surrounding prose is slightly dense but not padded.

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

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

For a 10-parameter, no-output-schema write tool with 100% schema coverage, the description supplies what the schema cannot: when to call it, why the soft-required fields matter, and how the `against` entries are validated. The remaining fields (ref, root, parent, governs, supersedes) are self-documented in the schema, so nothing an agent needs to call it correctly is missing.

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

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 and the schema already carries most field meaning. The description still adds real value beyond it by explaining that `alternative` is behaviorally mandatory despite being schema-optional, and by clarifying the intended content of `against` (a pillar id plus one sentence on how it holds).

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

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

The description opens with a specific verb+resource: 'Record a decision, with the reason it was made and every alternative that lost.' That is unambiguous and tells an agent exactly what artifact gets produced, and the 'decision vs datum' framing subtly separates it from a plain note tool. It stops short of naming which sibling to prefer (vivac_note, vivac_declare), so a 4 rather than a 5.

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

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

It gives an explicit timing rule — 'the moment a choice is actually settled, not before and not long after' — plus the operative constraint that alternatives are 'optional in the schema and not in practice,' with the consequence spelled out (the same option gets re-proposed in a month). This is exactly the when-to-use guidance an agent needs, including the counter-intuitive case where a schema-optional field is effectively required.

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

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

Annotations already declare this is a non-read-only, non-destructive write. The description adds behavioral detail beyond that: it only augments an existing decision (no creation), re-declaring the same rule replaces its sentence, and the judgment is timestamped as 'late' in the decision's history. It does not say what happens if the id does not exist, which is the notable gap.

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

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

The core purpose is front-loaded in the first clause, which is good. However the 'Call it the moment the judging happens -- someone asks whether a decision holds...' sentence is atmospheric narration that conveys little operational information and could be compressed to 'records the judgment after the fact, so it shows as late in history'. Middle section is bloated relative to the payload.

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

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

For a 2-parameter tool with full schema coverage and no output schema, the description covers purpose, scope, sibling routing, and update semantics adequately. The main omission is failure behavior when the referenced decision does not exist, plus no mention of how the declaration surfaces in other views.

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

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

Schema coverage is 100%, so both `id` and `against` are already documented with concrete formats ('d12', '

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

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

The description states a specific action (record, after the fact, the pillars or rules a decision was judged against, each with a sentence) and immediately scopes it to decisions that already exist. An agent can tell this is an additive annotation of existing decisions rather than creation. The 'moment the judging happens' framing adds some color but the operational purpose is clear.

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

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

It routes explicitly: new decisions take their judging context through `vivac_decide`, and `vivac_rules` is named as the source of the pillars/rules to reference. That gives real when-this-vs-that guidance for two siblings. It stops short of enumerating all alternatives, but the key routing decisions are covered.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds real behavioral context beyond them: a guard that refuses to close over open closure conditions, the terminal-only '--force' escape hatch, and the human-visibility requirement. It stops short of saying what happens to a partially-resolved node's remaining data.

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

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

Three compact sentences, front-loaded with the action, then the trigger condition, then the guard and alternative. Efficient, though the dense domain vocabulary ('closure conditions,' 'a record, whose outcome starts with Record:') makes it read as compressed rather than clean.

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

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

With only 2 parameters, full schema coverage, and no output schema, the description covers the action, trigger, guard, and alternative to vivac_pop. What is missing is the failure/return behavior when the closure guard blocks the call, which an agent would benefit from knowing.

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

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

Schema coverage is 100%, so both 'id' and 'outcome' are already documented by the schema. The description reinforces the Record: prefix convention for outcome but adds no syntax or format detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb+resource: 'close a node that is not the focus, recording what came of it,' and explicitly contrasts with 'vivac_pop closes the focus.' The scope term 'not the focus' is domain jargon that assumes familiarity, but the core action and its sibling boundary are identifiable.

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

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

Gives concrete invocation conditions ('right after writing a lesson or a measurement that asks nothing of anyone... or work that was finished somewhere else') and a when-not ('never closes over open closure conditions'). It routes the agent to vivac_pop for the focus case but does not enumerate how other siblings (e.g. vivac_add, vivac_push) differ.

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

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

Annotations already cover safety (readOnly, non-destructive, closed-world), and the description adds real behavioral value beyond them: a full ranking model (title hit > note hit, node supporting more of the tree > less, recency last) and the fact that closed/finished nodes are still returned. It omits any limits, pagination, or cost, keeping it from 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.

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

Front-loaded with purpose, then ranking, then scope, in four tight sentences with no filler. The ranking clause is dense but each clause conveys a distinct tiebreak rule; the closing aphorism is flavor but brief. Efficient overall.

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

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

There is no output schema, so the description carries the return burden and does so: each hit comes 'with the lineage it hangs from,' best-first. With readOnly annotations covering safety and 100% param coverage, an agent has what it needs to call this correctly; only pagination/limit expectations are unaddressed.

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

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

Schema coverage is 100%, so schema already documents both parameters (baseline 3). The description goes further for 'query' by naming the searched fields (title, reason, note, outcome) and the all-terms requirement, adding meaning over the schema. It adds nothing about the 'everywhere' cross-project flag, so not a 5.

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

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

States a specific verb and resource: 'Search the provenance tree' and returns nodes whose fields contain the terms, with lineage. This is clearly a text-search tool. It does not explicitly contrast itself with siblings like vivac_why or vivac_brief, which might also retrieve nodes, so it falls short of the top tier.

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

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

Usage is implied rather than stated: an agent can infer 'use this to find nodes by keyword,' and the note that closed nodes are included signals when it stays useful (long-after-the-fact lookups). But no explicit when-to-use or when-to-prefer-an-alternative statement is given, and no sibling is named.

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

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

Annotations already disclose the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real value beyond them: the note does not alter node state or the stack, and it is not itself a node. It does not address what happens on repeated calls despite idempotentHint=false, which is a minor remaining gap.

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

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

Front-loaded with the core action, then routing to siblings; roughly three tight clauses with no wasted preamble. The aside 'nobody rereads' is rhetorical flavor that slightly dilutes the density but does not obscure the instruction.

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

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

A two-parameter, no-output tool with full schema coverage and annotations present; the description supplies the decision logic an agent needs (note vs. push/pop vs. add) and the non-mutating guarantee. Only the repeat-call/visibility behavior of notes is left unstated, which is a minor omission.

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

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

Schema description coverage is 100%: the id parameter's 'Defaults to the current focus' and note's 'The fact to attach' are already documented in the schema. The description adds no syntax, format, or length guidance beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Attach a fact to a node') and immediately delimits the scope ('without changing its state or the stack'). It explicitly distinguishes itself from vivac_push, vivac_pop, and vivac_add, so an agent can route without opening sibling schemas.

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

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

Gives a positive use case (facts that would otherwise only live in a chat transcript, called alongside vivac_push/vivac_pop) and an explicit exclusion with a named alternative: if the fact 'deserves to be found on its own -- a finding, a measurement' use vivac_add. Both when-to-use and when-not are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the sort order (blockers first, then most-blocking, then newest), the returned fields (alias, kind, state, title, ancestors), and the handoff to vivac_why for more. It doesn't mention output size or pagination behavior, keeping 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.

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

Front-loaded with the core purpose, and each subsequent clause adds real information (selection rule, ordering, return shape, routing). The ordering clause is dense and slightly cryptic ('holding up the most tree'), but nothing is padding.

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

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 carry the return value, and it does: alias, kind, state, title and the ancestor aliases, plus a pointer to vivac_why. Combined with annotations covering safety and zero parameters, an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning to add. The description correctly avoids implying any filters or options.

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

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

States a specific verb+resource ('List what is still unfinished in this project') and goes further by defining the exact selection rule: nodes with nothing open under them. It then distinguishes itself from siblings by naming vivac_brief and vivac_find, so an agent can route correctly without reading other schemas.

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

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

Explicitly states its purpose ('Use it to answer what is left or what is waiting') and names the alternatives with the condition that selects them: vivac_brief for session state, vivac_find for word-based lookup. When-to-use and when-to-use-something-else are both covered.

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

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

Annotations only declare the safety profile (not read-only, not idempotent, not destructive) and leave the lifecycle opaque. The description fills that gap: the node stays parked until reclaimed and resurfaces in vivac_brief under BACK FROM PARKED on/after the until day, which is meaningful state-change context beyond the annotations.

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

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

Four sentences, all substantive and front-loaded, with the core 'not now, not finished' idea leading. Slightly verbose in the final routing sentence but every clause carries decision-relevant information.

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

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

For a mutation tool with no output schema, the description covers the full lifecycle an agent needs: what happens to the node, how it returns (BACK FROM PARKED), how long it stays parked, and how to handle a node not yet in the tree. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents id, until, and reason in detail, including the YYYY-MM-DD format and the BACK FROM PARKED return behavior. The description restates the same conceptual behavior rather than adding new syntax or constraints, so the baseline 3 is appropriate.

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

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

The description states a specific action (suspend a node without abandoning it) and its immediate effect (drops off the stack, becomes something a later session is told not to touch). It explicitly distinguishes itself from siblings vivac_pop and vivac_add, so an agent can disambiguate without opening any schema.

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

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

It gives explicit triggers ('when the person says not now, or when work is stuck on something outside this session'), an explicit exclusion ('never as a substitute for vivac_pop on something that is simply finished'), and a prerequisite routing ('if it is not in the tree yet, file it with vivac_add and park that'). Nothing about when to choose this tool is left to inference.

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

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

Adds a real guard behavior beyond annotations: a node with open closure conditions refuses to close on its own, and force overrides this while leaving a trace. That refusal/override mechanic is genuinely useful and not derivable from readOnlyHint=false / destructiveHint=false. It does not describe permissions, cost, or what state is otherwise mutated, so it is not exhaustive.

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

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

Front-loaded with the core action, then the call condition, then the guard. Dense but every clause carries information. The long em-dash sentences and the second-person aside make it slightly harder to scan than it needs to be.

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

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

No output schema exists, and the description explains the stack/closure semantics and the force escape hatch that an agent needs to call this correctly. Nothing critical is missing, though it could say more about what happens to recorded outcome/next data after the pop.

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

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

Schema description coverage is 100%, so the schema already fully documents next, force, and outcome. The description reinforces the intent (force overrides open conditions) but adds little syntactic or format detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a concrete verb and resource: "Close the current focus and step back to its parent, recording what came of it." It ties itself to the vivac_push workflow, so an agent can place it in the stack. It stops short of contrasting with other status-changing siblings like vivac_done or vivac_park, so the boundary is slightly blurry.

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

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

Explicit when-to-use: "Call it once the work vivac_push opened is actually finished." Explicit when-not: "not on a whim to clear the stack." It even gives the recursive rule ("pop again" if the work also settles the parent), leaving nothing to inference.

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

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

Annotations declare this is a non-idempotent mutation that is not destructive; the description adds substantial behavior beyond that: the stack push semantics, the requirement that it be matched by a pop, the root-vs-focus targeting, and the mandatory `why`. It stops short of describing permissions or failure modes on a closed/parked node (those live in the schema), so a 4 rather than 5.

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

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

Front-loaded with the core action and structured as action -> when -> routing -> params. Four dense sentences with some evocative framing ('a detour worth its own trace', 'once the reason... has already faded') that costs a little efficiency but earns its place by motivating the tool's constraints.

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

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

For an 11-parameter mutation tool with no output schema but 100% schema description coverage, the description supplies the mental model (focus stack, matching pop, parent/root targeting) an agent needs. Remaining gaps (exact refusal conditions, return payload) are adequately covered by the schema, so it is complete enough.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value on the two most decision-critical params: `parent` names the node this work continues (or `root` when it continues nothing) and `why` is called out as mandatory. These reinforce the mutual exclusion and the required field beyond the raw schema text.

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

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

States a specific verb+resource with precise scope: 'Open a node and step into it: it becomes the focus, and everything captured next hangs from it until a matching pop.' This clearly separates it from siblings like vivac_pop (the matching counterpart), vivac_find (lookup) and vivac_open.

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

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

Gives explicit when-to-use ('the moment a new line of work starts or forks away'), when-not ('never after the fact, once the reason... has already faded'), and names the alternative 'Look first with `vivac_find`' with the condition that selects it. Nothing is left to inference.

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

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

Annotations already establish read-only, non-destructive, closed-world behavior. The description adds genuinely non-obvious operational context: commands are folder-relative to the folder holding .vivac, running them elsewhere 'can pass without checking anything,' and the tool only supplies rules while 'the judging is yours.' It stops short of describing volume or pagination.

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

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

Front-loaded with the payload ('What governs this project: ...') and free of filler sentences. Some clauses are densely nested ('each with the folder it runs in, relative to the folder that holds .vivac, or none, which means it is judged'), which costs a little readability but the length is justified for a no-parameter tool whose return shape has no output schema.

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

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

With no output schema, the description carries the full burden and does: it describes the return shape, the field meanings, the empty-result case, the consumption caveat, and the follow-up action. Nothing an agent needs in order to call and use this correctly appears to be missing.

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

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

Zero parameters, so per the rubric the baseline is 4 and there is nothing for the description to add or omit. The schema is trivially complete.

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

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

States a specific resource and enumerates its contents: pillars, rules under them, rules without a pillar, and invariants. It also describes the internal structure of each element (title says what a pillar rejects, rules carry verifying commands). It does not name or contrast any sibling tool (e.g. vivac_brief, vivac_declare), so differentiation is left to the caller.

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

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

Gives an explicit trigger: 'Read it whenever you are asked to check work against the project's rules, whether or not they arrived when the session opened.' It also covers the alternative path for the empty case, routing the agent to vivac_add with a concrete procedure (propose pillars/rules, let the person decide, write them).

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

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

Beyond the annotations, it discloses append-only behavior ('adds a new stop and never replaces an earlier one'), that it 'neither moves the focus nor closes anything,' how the result interacts with vivac_brief, and even what the return payload contains (uncommitted files, unpushed commits, unclaimed changes). This is rich behavioral context the annotations alone do not convey.

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

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

Purpose and the append-only guarantee are front-loaded, and each sentence contributes meaning. It is on the longer side, but no sentence is pure filler, so it stays efficient.

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

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

With no output schema, the description compensates by describing the result ('says what the stop found unfinished: files not committed, commits not pushed, and files changed that no node claims'). Combined with usage triggers and behavioral rules, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented. The description's framing ('what was about to happen next') restates the schema rather than adding syntax or edge-case detail, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Record a safe stop') and immediately defines what a stop is: 'a label for this point and what was about to happen next.' It explicitly distinguishes itself from siblings by naming vivac_park and vivac_note and their different purposes.

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

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

It states exactly when to call it ('at a clean seam: before the session ends, before a long pause or a handoff, or when the person asks for a safe point') and routes the agent to alternatives for adjacent needs ('To set a node aside, vivac_park; to keep a fact on one, vivac_note'). Nothing is left to inference.

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

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

Annotations already declare read-only, non-destructive, and closed-world behavior. The description adds useful output truncation rules: open siblings and children are capped at eight, every blocking one is kept, the newest three notes come whole with the rest counted, and 'full' brings them all.

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

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

The purpose is front-loaded and the description is only four sentences. The second sentence ('This is the question the whole tool exists to answer') is slightly redundant but adds emphasis; otherwise there is little waste.

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

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

Given no output schema, the description covers the return content (chain, open in parallel, born from it, blocks closing) and output limits. It lacks detail on what 'blocking' means or how to interpret the chain, but is otherwise complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description's closing sentence reinforces the 'only' parameter's purpose, but the schema already documents that. The mention of 'full' also mirrors the schema description without adding syntax or format details beyond it.

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

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

The description states a specific purpose: it returns the chain from the goal down to a node, what is open in parallel, what was born from it, and what blocks it from closing. It is clear but does not explicitly differentiate itself from siblings like vivac_brief or vivac_find.

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

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

It provides a concrete usage pattern for sequential sibling queries: 'Walking siblings one after another, pass only: their shared path came with the first.' No explicit alternatives or when-not conditions are named, so it falls short of a 5.

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