vivac

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already mark this tool as destructive and non-idempotent, so the description adds valuable safety context: assist and compare read without writing, apply requires review plus explicit confirmation, detached files stay excluded, and unreviewed overwrite digests are rejected. It still does not fully define what authorization entails or exactly what gets overwritten in destructive apply cases.

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, but the remainder is a dense semicolon-separated stream of fragments with no grouping by operation or lifecycle stage. It is compact yet hard to scan and parse, which undermines structure despite avoiding obvious 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?

For a tool with 19 operations, 19 parameters, nested selection objects, and destructive apply behavior, the description leaves many operations unexplained, including scan, status, show, diff, add, set, retire, bind, adopt, detach, observe and import. With no output schema, return values are largely absent, and 'Exit 1 means remaining work' is only a minimal hint.

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 meaning beyond the schema: reasons belong in selection.why, assist selection takes references plus destination harnesses, and apply must reuse the identical selection and plan_digest with yes. Many operation-specific parameters are still left entirely 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?

The description states a specific verb and resource: manage explicitly selected native agents, and explicitly warns against defaulting to all. It also mentions transfers/sync and selection, but 'manage' spans many operations and the self-referential 'Use vivac-agents' line adds ambiguity rather than clear sibling differentiation.

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 useful procedural guidance such as inventory first, review plan/conflicts, and apply requiring identical selection, plan_digest, yes and authorization. However, it does not explain when to use each of the 19 operations or when to choose another vivac_* tool; the guidance is scattered and implied.

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 generic mutation profile (readOnlyHint false, destructiveHint false); the description adds the crucial behavioral fact that vivac 'stores but never runs it', so the agent knows no execution or side effects beyond storage occur. It also discloses the path-resolution behavior, which the schema states only tersely. No contradiction with 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?

Three short clauses, front-loaded with the action and then the constraint, with no padding. The clause 'Rules without executable checks remain judged' is slightly compressed to the point of ambiguity, which keeps it from 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?

For a four-parameter state-mutating tool with a fully documented schema and no output schema, the description covers what is stored, what is not executed, path scoping, and the off-removal path. It omits error conditions (unknown id, nonexistent dir) but nothing that would cause a misinvocation.

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 all four parameters are already documented in structured fields, and the description's note that the command is 'stored, never executed' is largely a restatement of the schema text. It adds only marginal, indirect meaning (e.g., dir is relative to tree root) rather than new semantics. 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 opens with a specific verb pair and resource: 'Attach or remove a rule verification command', which tells an agent exactly what state changes. It is distinguishable from data-oriented siblings like vivac_rules or vivac_find, though it never names a sibling to contrast with.

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 a clear when-not-to-use instruction ('do not invent a test to label them verified') and clarifies that rules without checks 'remain judged', which is genuine guidance about edge conditions. What is missing is routing guidance toward alternatives (e.g., vivac_rules for plain rule creation), so it stops 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.

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

With annotations declaring non-readonly, non-destructive and non-idempotent, the description still adds substantial behavior: restore never overwrites, check verifies the complete revision rather than paginated metadata, store check surfaces unrecorded objects, custody neither executes nor installs, strict privacy is the default, and PNG/MP4 require prior human review. It also warns never to enable allow_insecure_artifacts to retry a refusal. Remaining gaps are return shapes and idempotency semantics, which annotations only partially address.

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 text is a dense, semicolon-chained block with no headings, operation grouping, or front-loaded summary, drifting across capture, list, check, restore, policy, and limits in one paragraph. Nearly every clause carries real content, so the failure is structure rather than padding. An agent must parse sequentially to find, for example, the capture preconditions.

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 16-parameter, six-operation tool with no output schema and no examples, the description covers many constraints (privacy defaults, review requirements, provenance guards) but never maps operations to parameters or describes what each operation returns. It also introduces a 'policy' operation that the enum does not contain, which leaves the calling contract ambiguous. Adequate but with clear gaps for a tool of this complexity.

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 and each parameter is already documented, including 'stable identity, never inferred from filename' and 'conflicts with path'. The prose adds value mainly through combinatorial rules (path OR bundle, artifact plus previous to continue an identity, absent destination for restore), but repeats much of what the schema already states. That is a modest lift over the schema, not a substantive one.

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 purpose (retaining complete visual/interactive previews by default, other files requiring explicit delivery selection), but it is a multi-operation tool whose overall identity is never stated as a single sentence. The operation list in the prose ('capabilities, policy, list, show, capture, check or restore') does not match the enum, which omits 'policy', muddying what the tool actually does. An agent can extract the gist but must reassemble it from fragments.

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?

There are implied when-to-use rules per operation: 'Capture needs path OR bundle', 'List defaults to focus lineage; all lists the project', 'Continue an identity with artifact and previous'. It also steers toward self-contained frontends and says other file types need explicit delivery selection. However, no alternatives outside the tool are named, no explicit 'do not use when' guidance appears, and no operation-by-operation selection map is given.

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 a safe, read-only, closed-world, non-destructive operation, so the safety profile is covered without the description. The description adds content scope (what categories of state come back) but says nothing about freshness, cost, caching, or result format — and with no output schema, the shape of the return is left unstated. 'Avoid redundant fetches' hints at cost but never quantifies it.

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?

Two tight sentences with no filler: content scope first, usage condition second. It is telegraphic to the point of being a fragment ('Current focus/lineage, parked work and reasons...'), which costs a little readability but nothing is wasted.

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 zero-parameter, read-only context tool with no output schema, the description carries the main burden and does so by enumerating the returned content categories plus the trigger condition. What is missing is the response format or ordering and any sense of freshness, but for a simple briefing call the definition is sufficient to invoke 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Schema coverage is 100% trivially, and the description correctly implies no arguments are needed.

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 the specific payload of the brief — current focus/lineage, parked work and reasons, governing decisions, latest safe point/next step — which is concrete enough that an agent knows exactly what it gets back, distinct from a bare search (vivac_find) or explanation (vivac_why). The verb is omitted (it reads as a noun list rather than 'returns X'), and no sibling is named explicitly, so differentiation is implied rather than stated.

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?

'Use if opening context is missing/unverified or state changed' gives an explicit trigger condition, and 'avoid redundant fetches' supplies the when-not, which is unusually direct usage guidance. The gap is that it never names the alternative to call instead when the condition does not hold (e.g. vivac_find, vivac_open), leaving routing 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 a non-read-only, non-destructive, non-idempotent write, so the safety profile is already covered. The description adds genuinely new behavioral context by warning that rejected alternatives are 'semantically required even though optional in the schema,' which an agent would not learn from the annotations or schema alone. It still does not say what superseding does to the prior record or what the call returns.

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 opening sentence front-loads the core action well, but the following sentences are dense and shorthand-heavy ('Norms: use vivac_add constraint (root if global), even if called rules'), which costs clarity. Every sentence is relevant, yet the phrasing reads as internal jargon rather than clean 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?

For a ten-parameter write tool with no output schema, the description covers the most error-prone parameter ('alternative') and the 'against' convention, which is the right prioritization. It is silent on what the tool returns (node ID or confirmation) and on the semantics of 'supersedes' and 'governs', so an agent driving follow-up calls has gaps.

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 would be 3, but the description adds real meaning by upgrading 'alternative' from optional to semantically mandatory and by prescribing the 'against' format ('pillar/rule plus compliance sentence'). It leaves 'governs', 'blocks', and 'supersedes' entirely 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?

The description gives a concrete verb and resource: 'Record a settled choice ... its reason and every rejected alternative.' It is distinguishable from a general note-taking tool because it demands a reason and rejected options, but it never names the closest siblings (vivac_declare, vivac_note) to sharpen the boundary.

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 does route one case explicitly: constraints/norms should go to vivac_add rather than here, and 'against' should be filled per applicable pillar/rule. That is meaningful steering, but there is no guidance on when to choose this over vivac_declare or vivac_note, and the word 'now' hints at timing without explaining it.

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?

The annotations already declare this is a write (readOnlyHint=false), non-idempotent and non-destructive; the description's one added behavior is that repeating a criterion replaces its previous compliance sentence, which is genuinely useful upsert semantics. However, that replace behavior sits in slight tension with destructiveHint=false since prior compliance text is overwritten, and no permissions, error behavior, or effects on criteria not resubmitted are described.

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?

Two short sentences with no filler, and the core action is front-loaded ahead of the replacement rule. Slightly clipped grammar ('how an existing decision met') costs a bit of clarity but nothing is wasted.

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 two-parameter tool with full schema coverage, no output schema, and annotations supplying the safety profile, the description covers purpose and the one non-obvious mutation rule. It could still say what happens when the referenced decision does not exist, but the essentials for correct invocation are present.

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% and both parameters carry rich descriptions, including the 'r12: writes stay local' format and the 'Not constraints' exclusion, so the schema already does the heavy lifting. The description adds no syntax, formatting, or meaning beyond what the schema states, which is the baseline-3 case.

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 uses a concrete verb ('Record') and a specific resource ('how an existing decision met each governing pillar/rule'), so an agent understands this attaches compliance notes to an already-existing decision rather than creating one. It does not name or contrast any sibling (e.g. vivac_decide, vivac_rules, vivac_note), so sibling differentiation is left to inference.

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?

The word 'existing' implies a prerequisite (a decision node must already be in place) and the schema's 'Decision only' note reinforces scope, but the description never states when to prefer this over vivac_decide or vivac_note, and gives no exclusions or failure conditions. Usage is implied rather than prescribed.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false), it discloses a real precondition: unresolved conditions require an escalated '--force' path and human presence, which is safety context the annotation set does not convey. The gap is that '--force' and 'terminal done' reference a CLI construct absent from the input schema, so the agent cannot map that instruction onto an available parameter, and nothing is said about what happens to dependents of a closed node or about repeat calls on an already-closed id.

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 short sentences with the core routing constraint front-loaded ahead of the edge cases, and no filler. The sentences are densely packed with tool-specific jargon ('node', 'finding', 'Record:', 'terminal done --force'), which costs a little readability but keeps the definition compact.

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 two-parameter mutation tool with no output schema, the description covers purpose and routing well but leaves the escalation mechanism unexplained relative to the schema, and says nothing about post-close state or the non-idempotent behavior the annotations imply. An agent could still call it, but the '--force' sentence is orphaned.

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 with examples ('t4', 'for a record start with Record:'). The description reinforces the 'Record:' convention for findings but mostly restates what the schema says, adding little new meaning about format, length, or validation.

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 specific verb and resource ('Close a non-focus node with its outcome') and explicitly separates this tool from the sibling it could be confused with ('use pop for focus'). An agent can choose between vivac_done and vivac_pop without inspecting either 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 routing rules: non-focus nodes go here, focus nodes go to pop, findings that ask nothing use a 'Record:' outcome, and unresolved conditions need the terminal 'done --force' path with a person present. When-to-use, when-not-to-use, and the alternative are all 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavior: closed nodes are included, results come back ranked with lineage, and 'everywhere' crosses projects except private ones with an obligation to identify and surface the source project before applying its information. The main omission is any sense of result 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?

Two sentences, front-loaded with the search scope before the project-crossing caveat. The second sentence is a slightly compressed run-on ('everywhere crosses projects except private ones: identify the source project...'), but nothing is redundant.

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 two parameters, no output schema and read-only annotations, the description covers what is searched, what comes back (ranked hits plus lineage), and the cross-project constraint. Explaining the return payload is important here precisely because no output schema exists, and that is done at a high level.

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 documented, and the description largely mirrors the schema: 'all terms must match' restates the query description, and the project-crossing caveat restates 'everywhere'. It adds a little operational framing around provenance but nothing the schema does not already say. 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?

States a specific verb and resource: searching node text and history, with the notable scope detail that closed nodes are included and results are ranked with lineage. An agent can tell this is a text-search tool rather than a structural retrieval tool like vivac_open, though no sibling is named for contrast.

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 by the word 'search' and the mention of what is searched, but there is no explicit when-to-use framing, no condition distinguishing it from vivac_open or vivac_why, and no statement of when it should not be used. The agent must infer the choice from the sibling names alone.

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 a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds real behavior beyond that: 'without changing focus' and 'Excess notes without children are flagged', the latter warning of a lint-style consequence. It does not explain accumulation/dedup behavior, which matters given idempotentHint=false.

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

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

Four short sentences, front-loaded with the core action and followed by routing and warning information; nothing is padded. The aphoristic phrasing ('typed nodes, never notes') is dense but occasionally oblique.

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 two-parameter write with no output schema and full schema coverage, most of the burden is met, but two things an agent needs are missing: the effect of omitting `id`, and what the tool returns or how repeated notes accumulate. The 'flagged' warning is mentioned without saying by what or when.

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 description adds only the loose framing of a fact attached to a node. Notably it does not clarify what happens when the optional `id` is omitted (presumably attaching to the current focus node, which 'without changing focus' only vaguely gestures at). Baseline 3 applies when the schema carries the semantics.

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 says to 'attach progress or changes outside Git' and that 'CI/tracker/cloud facts belong here', which conveys the kind of fact being recorded, but it never plainly states that a note is attached to a specific node (only the title does). The contrast sentence about 'typed nodes' hints at the resource, yet an agent must infer the core verb+target from the title rather than the description.

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 a genuine when-not rule: 'Findings, choices and pending work need typed nodes, never notes', which routes the agent away from this tool toward sibling node-creating tools. It also gives a positive case ('CI/tracker/cloud facts'). It stops short of naming the alternative tools explicitly, so it is clear but not exhaustive.

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, openWorldHint=false and destructiveHint=false, so safety is covered; the description adds real value by disclosing sort order and the exact returned fields (identity, kind, state, title, lineage). It omits volume/pagination behavior, so an agent cannot know how large the result set may be.

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?

Two tightly packed sentences: ordering and return shape first, sibling routing second, with no filler. The density of domain terms ('leaf fronts', 'tree impact') makes it slightly demanding to parse but nothing is redundant.

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 listing return fields and does so; annotations cover safety. Remaining gaps are limits on result size and a definition of what counts as a 'front', which are modest for a zero-parameter read 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 no parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly adds no parameter discussion, matching the empty 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 resource ('unfinished leaf fronts') and its ordering (blockers first, then tree impact and recency), which distinguishes it from list-like siblings such as vivac_find and vivac_brief that are explicitly redirected. The verb is only implicit in the description (the title supplies 'List'), which keeps it just 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?

Explicitly routes three sibling tools by purpose: 'why for detail, brief for session orientation and find for text lookup', giving clear context for what this tool is not for. It does not state negative conditions or prerequisites for using vivac_open itself, so it falls short of full when/when-not guidance.

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 signal a non-read-only, non-idempotent, non-destructive mutation, so the safety bar is partly covered. The description adds real behavioral substance beyond that: the deferral removes the item from the brief and an 'until' date auto-returns it, and the reason must come from the person rather than be fabricated. It omits any note on permissions or how a park is later undone.

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 tight clauses with the core action front-loaded and no filler. The middle clause ('optional until returns it to the brief on that date') is grammatically compressed to the point of being slightly cryptic on first read, which costs it a point.

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 three-parameter, no-required-field mutation with no output schema, the description covers the action, the effect of the optional date, the prerequisite, and the constraint against fabricated deferrals. What remains uncovered — return shape and the exact unpark path — is modest, but not fully implied by the annotations.

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 all three parameters (id, until, reason) are already documented, making the baseline 3. The description reinforces the semantics — 'with their reason' clarifies the reason must be user-sourced, and 'optional until' matches the nullable return date — but adds no format or edge-case detail beyond 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?

The description opens with a specific verb and effect: 'Park work the person said to defer' — parking means deferring a node, and the title reinforces it. It implicitly touches siblings ('If no node exists, add it first' relates to vivac_add; 'reopen parked work' relates to vivac_open) but never names an alternative, so the differentiation is inferential rather than explicit.

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 clear trigger ('work the person said to defer') plus a guardrail ('Never invent deferral') and an explicit exclusion ('reopen parked work unasked'), which is stronger than most. It stops short of 5 because it never names the sibling tool to use instead for the reopen/add case, leaving that routing to inference from the sibling list.

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?

The annotations already declare this is a non-readOnly, non-destructive, non-idempotent mutation, and the description stays consistent with that. It adds genuinely useful behavior the annotations cannot express: unresolved closure conditions cause a refusal, and the forced path leaves a trace. What it omits is the consequence of a refusal (state left unchanged?) and how the recorded outcome surfaces afterward.

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 short sentences, front-loaded with the core action, and each clause carries distinct information about preconditions or sequencing. The phrase 'with outcome/next' is slightly compressed but not wasteful.

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 zero-required-parameter stack mutation with no output schema, the description covers purpose, refusal semantics, and repeat-call conditions. The main remaining gap is that the force parameter's trade-off is only hinted at through 'resolved conditions refuse', leaving the agent to consult the schema for what forcing actually records.

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 defines next, force, and outcome in detail; baseline 3 applies. The description's 'return to its parent with outcome/next' reinforces that both fields travel to the parent, but it says nothing extra about force or the 'Record:' convention for outcome.

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 verb and resource ('Close completed focus') plus the resulting effect ('return to its parent'), which is well beyond the tautological title. It never names its obvious counterpart vivac_push by name, so an agent must infer the push/pop pairing from the stack metaphor rather than from explicit sibling differentiation.

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 real when-not guidance ('do not pop merely to clear the stack') and a precondition for repeated invocation ('Pop again only if the parent is also settled'). It stops short of naming alternatives such as vivac_done or vivac_park for finishing work without unwinding the stack, which would have made routing unambiguous.

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 non-readOnly, non-destructive, non-idempotent, so the safety profile is covered. The description adds one genuinely useful behavioral fact not in annotations: 'Explicit parent rebuilds the stack without closing prior work', which tells the agent that focus moves without losing state. It does not say what push returns (the new node's ID, presumably), nor what happens on failure beyond what the schema states.

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?

It is compact, but written as a chain of telegraphic fragments with undefined domain jargon ('stack', 'focus', 'the seam') that requires prior knowledge of the vivac model. 'Capture at the seam, not after the work' is a timing heuristic with no stated referent, so the compression costs comprehension rather than buying it.

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 12 fully documented parameters and a clear annotation set, the description only needs to supply routing and stack semantics, and it mostly does: parent rebuild, root isolation, and the add-vs-push split. What is missing is whether the call returns a node handle the agent needs for subsequent pokes, and any distinction from vivac_open.

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 all 12 parameters are already documented, setting the baseline at 3. The description reinforces the required triple ('Give title, why and the parent it continues') and the root-vs-parent choice, but that conflict is already stated in the schema, so the added meaning is shallow.

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 opening clause 'Start/fork work and focus it' names a concrete action and its effect, and the title reinforces it ('Open a node and step into it'). It explicitly separates itself from two siblings ('match with pop', 'Record newly discovered findings/pending work with add instead'), though it never disambiguates against vivac_open, which is the closest name collision.

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?

Strong conditional guidance: 'Search first and continue existing work', 'root only if unrelated', and an explicit redirect ('...with add instead') give the agent when-to-use and when-not-to-use rules. The remaining gap is that vivac_open and vivac_declare are never mentioned as alternatives, so sibling selection at the tool boundary stays ambiguous.

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, closed-world, non-destructive behavior. The description adds useful behavioral detail: commands must be run in their declared folder relative to the tree, rules without commands require judgement, titles state what pillars reject, and commands must not be confused with proof. The phrase 'then record it' is slightly ambiguous for a read-only tool, but it can be read as guidance to record via another 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 description is front-loaded and information-dense, with each sentence adding a rule or constraint. It is appropriately sized for the procedural guidance, though the branch about recording governance could be phrased more cleanly.

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 zero-parameter read-only tool with no output schema, the description covers purpose, usage, command execution, missing-governance handling, and key constraints. It does not describe the return format or structure of the governance data, but that is a minor gap given the tool's simplicity.

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 has zero parameters, so the baseline is 4. No parameter semantics are needed, and the description does not waste space restating schema details.

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, 'Read', and enumerates the resources returned: pillars, rules including unparented ones, verification commands, and invariants. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as vivac_decide or vivac_why.

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 clearly says to read this before judging or deciding, and gives a procedure for when the tree lacks governance but project instructions define it: propose mapping, obtain approval, then record. It lacks explicit when-not guidance or named alternative tools, but the usage context is clear.

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 write/non-destructive/non-idempotent/openWorld=false, so the safety profile is covered; the description still adds real value by disclosing append semantics ('preserving earlier stops without moving/closing focus') and by reporting uncommitted, unpushed and unclaimed changes since no output schema exists. It does not say whether repeated calls create duplicate stops or how focus interacts with the save, which matters given idempotentHint=false.

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

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

Three short sentences, front-loaded with the action and scope, then usage, then return content, then the read/write boundary. No filler; the telegraphic density is deliberate and each clause carries 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?

With two optional params, no output schema, and a non-destructive write, the description covers what an agent needs: when to call it, that it appends rather than replaces, and what the call reports back. The only residual gap is non-idempotency behavior on repeat calls, which is left to the annotation hint alone.

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% and both parameters are documented in-schema, so the baseline of 3 applies. The description restates 'label and next step' but adds no format, length, or defaulting nuance (e.g., what happens when label is omitted) beyond what the schema already says.

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: recording a safe point with a label and a next step, and adds differentiating scope ('preserving earlier stops without moving/closing focus'). The closing 'it does not read the last stop' separates it from read-side siblings. It stops short of naming which sibling (vivac_park, vivac_done, vivac_pop) is the near-miss alternative for the same workflow.

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?

'Use before stopping or handing off' gives an explicit trigger condition, and 'This writes; it does not read the last stop' supplies an implicit when-not. There is no explicit exclusion naming the sibling to use when the agent actually wants to read or retrieve state, so the routing guidance is clear but not complete.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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