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 establish read-only, non-destructive, closed-world behavior, so the description does not need to restate safety. It goes further by disclosing the ranking algorithm (title > note, node supporting more tree ranks higher, recency last) and that each result carries its lineage — genuinely useful traits not present in 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, front-loaded with the core action and filtering rule, then ranking, then the closed-node caveat. Mostly earns its space, though 'what you look for months later is usually finished' is slightly rhetorical 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 carries the return-value burden and does so: it promises all matching nodes, best-first, each with its lineage. Ranking rules and the closed-node inclusion policy complete the picture an agent needs to interpret results.

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 baseline is 3, but the description adds real semantics beyond the schema: matching is conjunctive across title/reason/note/outcome, which tells the agent to expect zero results for loose multi-word queries. The 'everywhere' flag's effect is left to the schema.

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 immediately scopes what is matched: nodes whose title, reason, note or outcome contains ALL terms. That distinguishes it from sibling read tools like vivac_why or vivac_brief, which serve different retrieval intents.

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: 'what you look for months later is usually finished' signals the case where closed nodes matter, and the ranking note hints at search-vs-browse. But no sibling is named as an alternative and no when-not-to-use condition is given, so an agent must infer routing among the 14 vivac_* tools.

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 state the safety profile (not read-only, not destructive, not idempotent), so the description contributes real behavioral information: the node leaves the stack and is later flagged as untouchable, and the reason string is read back verbatim under a DO NOT TOUCH NOW label. It does not say how a parked node is resumed or whether parking is reversible, which leaves one meaningful gap for a state-mutating tool.

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 action and its effect are front-loaded in the first clause, and the remaining sentences each carry distinct information (triggers, exclusion, precondition). Slightly conversational phrasing ('something a later session is told not to touch') costs a little 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?

No output schema exists, so the description needs to convey what happens on success, and it does: the node leaves the stack and is marked do-not-touch. Combined with annotations covering the safety profile and near-complete parameter docs, an agent has what it needs to invoke this correctly; only the reverse operation (how to resume) is 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 both parameters are documented structurally, and the schema already covers the default-to-current-focus behavior and the reason field's rendering. The description still adds a semantic constraint beyond the schema: the id must reference a node already in the tree, otherwise vivac_add is required first.

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?

Names a specific verb and resource (park a node) and states the distinctive effect: it drops off the stack and becomes something a later session is told not to touch. It explicitly distinguishes itself from the closest sibling, vivac_pop, which is a parenthetical rather than a definitional detail.

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 trigger conditions ('when the person says not now, or when work is stuck on something outside this session') and an explicit exclusion ('never as a substitute for vivac_pop on something that is simply finished'). It also supplies the precondition workflow: if the node isn't in the tree yet, file it with vivac_add first.

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 readOnly=false, destructive=false, idempotent=false, but the description adds behavior annotations cannot express: a node with open closure conditions refuses to close, and the tool steps back to its parent. That refusal/guard semantics is genuinely new context. It stops short of saying what the recording produces or how the parent transition behaves on force.

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 action in the opening clause, and nearly every sentence does work (when to call, misuse warning, recursion). The prose is somewhat ornate ('the mistake that refusal exists to catch'), which costs a little density but stays within a reasonable size for a guarded mutation.

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, so the description must carry the behavior, and it covers triggering condition, refusal guard, and recursive stepping well. It leaves unstated what a successful close returns or how force interacts with the trace, which is a minor gap for a non-idempotent mutation.

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 only gestures at recording ('recording what came of it'), adding no syntax, format, or default guidance beyond the schema. 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 first sentence names a specific verb and resource ('Close the current focus and step back to its parent, recording what came of it') and ties the tool to the sibling vivac_push, so an agent can distinguish pop from push without opening either schema. The domain vocabulary ('focus', 'node') is consistent with the sibling naming.

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 ('once the work vivac_push opened is actually finished'), explicitly rules out a misuse ('not on a whim to clear the stack'), and even gives recursive guidance ('if the work also settles that node ... pop again'). Alternative-condition routing is explicit rather than inferred.

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, the description explains that each call appends a new stop, never replaces an earlier one, and does not move focus or close anything. It also describes the downstream effect on vivac_brief and how future sessions resume, which is valuable behavioral context.

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 description is front-loaded with the core action and parameter meaning, then adds behavioral and usage context in a logical order. Every sentence contributes either behavior, call timing, or sibling routing guidance.

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 non-destructive append-style tool with annotations covering safety hints and no output schema, the description supplies purpose, behavior, usage conditions, and alternatives. Nothing essential for correct invocation 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?

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description restates the label and next-step meaning but does not add syntax, formatting, or additional semantic detail beyond what the schema provides.

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 and resource: recording a safe stop with a label and next-step note. It distinguishes the tool from siblings by naming vivac_park and vivac_note for adjacent needs, so an agent can tell what this tool is for without opening the 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 call conditions: before a session ends, before a long pause or handoff, or when the person asks for a safe point. It also names alternatives and their purposes: vivac_park to set a node aside and vivac_note to keep a fact on one.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral detail beyond the annotations: results are truncated to eight open siblings and eight open children, every blocking item is retained, and full lifts the caps. That truncation behavior is valuable for interpreting results.

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 purpose and the composition of the answer, with the cap behavior last where it belongs. The line 'This is the question the whole tool exists to answer' is partly rhetorical and does not encode new facts, keeping it just short of a 5.

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 burden of describing the return, and it does: the goal-to-node chain, parallel-open items, descendants, blockers, and the eight-item caps. For a read-only query tool this is nearly sufficient; only explicit sibling differentiation 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, full, and project, and the description largely restates the eight-item cap that the schema's full description already mentions. It adds the 'every blocking one kept' rule, a minor increment, so the baseline 3 for schema-driven parameters 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 capability with concrete scope: the chain from goal to node, parallel-open items, descendants, and blockers. It reads as a distinct 'explain a node's rationale' tool. It does not explicitly name a sibling (brief, open, find) it differs from, 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?

It asserts 'This is the question the whole tool exists to answer,' implying this is the canonical rationale query, and it enables deeper retrieval via full. But there is no explicit when-to-use/when-not, no routing against vivac_brief or vivac_open, and no stated prerequisites, so usage is only implied.

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