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

With no annotations, the description carries the full burden and does so well: it discloses state-dependent behavior (skills diff-since-last-boot on repeat boots, where empty means 'nothing new'), slot precedence ('resume > handoff > lessons > facts > brief'), and overflow reporting via budget.dropped. It also explains role inference and sibling-session scope (~60 min, max 5).

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

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

Front-loaded with purpose and gets denser but rarely wastes a sentence — the trigger examples and slot/resume rules all earn their place. It is a long wall of text, however, and could be broken into scannable lines for faster parsing.

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, yet the description enumerates the returned pack structure in detail (agent, session.role, resume, handoff, lessons, facts, brief, skills, repo_map, siblings, budget, client) and explains how each conditional branch is populated. An agent has everything needed to call it and interpret the response.

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 already 100%, so the baseline is 3, but the description adds real meaning beyond the schema: 'goal' drives facts/lessons/skills retrieval AND role inference, 'full:true' overrides the diff behavior, and 'project_id' gates the goal-graph brief. It adds useful semantics for the highest-impact parameters rather than just restating names.

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 ('Boot an autonomous agent') plus the distinguishing value proposition: a single token-budgeted call returning everything to start or resume work. It clearly positions itself apart from siblings like agent_session_start and agent_resume, and even names relay_* for coordination.

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

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

Explicit routing: 'Call this FIRST in any agent run', a concrete trigger list for resume/catch-up work (with multilingual examples), and an explicit exclusion ('Skip for unrelated casual questions'). Also states when the resume/handoff/skills branches activate, so an agent knows exactly when this beats alternatives.

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 no annotations, the description carries the full behavioral burden. It usefully discloses what gets stored (arbitrary JSON: cursor, partial results, plan, open files) and the return value (checkpoint plus monotonic seq), but says nothing about whether it overwrites prior checkpoints, lifecycle/consumption by resume, or permission needs.

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 tight sentences, front-loaded with the purpose, then payload semantics, then return value, then cadence. No filler and every sentence carries a distinct fact.

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

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

Given no annotations and no output schema, the description supplies the essential missing context: payload shape, return value, and call cadence. It is largely sufficient for correct invocation, with the only gaps being overwrite/lifecycle behavior.

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 earns extra by expanding `state` into concrete examples (cursor, partial results, plan, open files) and clarifying `summary` as a one-line 'where I am', adding meaning beyond the terse schema strings. It does not address `token_estimate` or `session_id` 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?

Specific verb ('Snapshot') plus resource ('the agent's working state') with an explicit goal ('so a restart/crash can resume from exactly here'). It distinguishes itself from the surrounding ctx_* and agent_* siblings functionally via the resume framing, though it never names an alternative tool directly.

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?

'Call periodically after each chunk of progress' gives a clear triggering condition for use. There is no when-not guidance and no explicit routing to siblings like agent_handoff or ctx_save, 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 no annotations, the description carries the full burden and does meaningful work: it discloses the LLM-synthesized nature, that handoff context is linked back to the session, the side effect of complete=true marking the session completed, and the hard prerequisite of a configured LLM provider. It omits reversibility of the completed status and any auth/permission needs.

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 produced and finished with the prerequisite; the parenthetical content list is information-dense rather than filler. Slightly packed but every clause earns its place.

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 6-param, no-annotation, no-output-schema mutation tool, the description covers the artifact produced, the main side effect, and the LLM prerequisite. It does not describe what happens to the returned handoff or how errors surface when no provider is configured, leaving a small 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%, so every parameter (dry_run, project, complete, workspace, since_days, session_id) is already documented in the schema. The description only reiterates complete=true and adds that workspace falls back to the session's workspace implicitly; 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+resource ('Generate a handoff document for the session's workspace') and enumerates contents (TL;DR, in-progress, next-steps, open-questions), so an agent knows exactly what artifact is produced. It does not explicitly differentiate itself from nearby siblings like agent_checkpoint or agent_session_end, which is the only thing keeping it from 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?

Clear context: call 'at run end', and pass complete=true to additionally close the session. It also states the prerequisite that an LLM provider must be configured. No explicit when-not or named alternative to sibling tools, 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?

No annotations are provided, so the description carries the full burden and does a decent job: it discloses the post-write behavior (embedded for goal-relevant recall at the next agent_boot) and unpacks the scope enum's effect ('session'/'agent'/'workspace'). It omits any dedup, overwrite, or permission behavior, but the core trait an agent needs is disclosed.

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 front-loaded sentences that lead with the action and its payoff. The 'Mirrors the vibe-loop Lessons log' clause is mildly incidental jargon, but overall it is tight and well-ordered.

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 no annotations and no output schema, the description covers purpose, timing, scope semantics, and downstream recall behavior. It leaves lifecycle details (overwrite, dedup, author attribution) unspecified, which is a minor gap rather than a blocking one.

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 all five parameters. The description adds genuine meaning for scope's three breadth tiers, but says nothing about what_failed, why, try_instead, or session_id beyond the self-evident schema text. 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 ('Record a lesson learned during a run') plus the outcome it serves ('so the agent doesn't repeat the failure'). An agent understands the intent immediately, though the description never explicitly separates this from the similarly-named ctx_remember sibling.

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?

Clear context: record a lesson after a run so it is recalled at the next agent_boot, with scope controlling breadth. It implies when to use it but names no exclusion or alternative, so it stops short of routing the agent away from ctx_remember or similar siblings.

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?

No annotations are provided, so the description carries the burden, and it does disclose the read-only nature plus the exact contents of the returned bundle (checkpoint, task statuses, lessons). It omits any note on permissions, side effects, or idempotency, which keeps it out of the top tier.

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 compact sentences, front-loaded with what the tool returns, then the usage condition. No filler and every clause earns its place.

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

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

With no output schema, the description compensates by enumerating the bundle contents, and the single-parameter read tool needs nothing more. An agent has everything required to call it correctly.

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

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

Only one parameter with 100% schema coverage, so the schema already documents session_id. The description adds marginal context by implying the id must be known in advance, but no format or source details 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?

States a specific verb (Read) and resource (resume bundle), and enumerates the exact contents returned: latest checkpoint, open tasks, and goal-relevant lessons. The 'WITHOUT booting fresh' clause cleanly distinguishes it from the agent_boot sibling.

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 triggering condition ('when you already know the session_id and just need to reload where you left off') and contrasts behaviorally with booting fresh. It stops short of naming agent_boot explicitly as the alternative to use when the session_id is unknown.

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 no annotations, the description carries the full disclosure burden and does add real behavior: completed/abandoned stamp ended_at, paused preserves a resumable checkpoint, stalled ties to the vibe-loop stall detector. It stops short of stating whether ending destroys session data, permission requirements, or what happens to associated tasks.

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?

A single dense sentence that front-loads the core action and then enumerates statuses without filler. Every clause carries usable information; nothing is redundant with annotations or 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?

Given 4 params including a nested metadata object and no output schema, the description covers status semantics and one side effect well. The metadata merge behavior and the return shape rely entirely on the schema, which is acceptable but leaves the nested-object handling underexplained.

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 goes further by giving operational meaning to the status enum values that the schema only labels 'New session status'. It also clarifies that goal optionally revises (rather than replaces) the goal, matching the schema's 'Optionally revise the goal'.

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 ('End or update an agent session's status') and clarifies the scope is status/goal/metadata rather than the broader lifecycle handled by agent_session_start, agent_resume, or agent_checkpoint. An agent can distinguish it from siblings without opening a 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?

The description maps each status value to an explicit condition: 'completed' when the goal is met, 'paused' to suspend and resume later, 'stalled' when the stall detector trips, 'abandoned' to drop the run. That is high-quality when-to-use guidance, though it never names a sibling alternative or states when not to call this tool.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that a session is created and that the response includes the id, but says nothing about side effects, whether re-calling with the same agent/goal is idempotent or duplicates, or error behavior for a mutation-style 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?

Three sentences, each earning its place: definition, return value, and usage trigger come first, with the parent_session_id note last. No filler or redundancy.

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 8-parameter creation tool with no annotations and no output schema, the description covers purpose, usage, and the return shape adequately. It omits behavioral details that matter for a creation call, such as what happens to existing sessions or how errors surface.

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 description adds genuine meaning only for parent_session_id ('chain a resumed run to its predecessor'), while the other seven parameters are 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?

States a specific verb+resource ('Start a new agent session') and clarifies the domain term as 'a run with a goal', so an agent knows exactly what is being created. It does not explicitly name the sibling it contrasts with (agent_resume), leaving some differentiation 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?

Gives a clear trigger ('Use when beginning a fresh task that you want to track and resume') plus a specific conditional for parent_session_id. It stops short of stating when NOT to use it versus agent_resume or where a resumed run belongs.

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 no annotations provided, the description carries the full burden and does so well: it discloses the no-self-certification rule, that status='verified' requires non-empty evidence, and the 400 failure mode. It stops short of stating reversibility, idempotency, or what a successful call returns, which are the remaining gaps.

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 the hard constraint, then the trigger guidance. Dense but every clause carries information; the parenthetical phrase list is slightly verbose but serves a routing purpose.

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 3-param mutation tool with no annotations and no output schema, the definition supplies the conditional requirement, the error behavior, the routing trigger, and the sibling alternative. Only the success response shape and state-transition semantics are left unstated, which is 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it ties the `evidence` parameter to a specific semantic requirement (real observed output such as test result, HTTP status, exit code) and couples it conditionally to status='verified'. That is meaningfully beyond the bare 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 ('Flip a task's status') and immediately distinguishes itself from the sibling goal_advance, which handles board-level tasks. An agent can tell exactly what this does and what it is not.

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

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

Explicit trigger conditions are given ('user reports finishing a piece of tracked work' with concrete phrases), an exclusion is stated ('ignore unrelated casual chatter'), and the alternative tool is named for the board-level case. This is close to ideal routing 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?

No annotations, so the description carries the full behavioral burden. It does add real context the schema lacks — that verify_cmd must be run before ticking, and that the item is session-scoped — but it says nothing about update semantics (overwrite vs. merge of omitted fields), required permissions, or error behavior for a mutation tool with 9 params.

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 create/update distinction and the trigger in a compact block. One sentence — 'This productizes the vibe goal-file checklist' — is internal jargon that earns no place and costs clarity, but the rest is tight.

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 9-parameter, no-annotation, no-output-schema mutation tool, the usage and routing story is complete but the mutation contract is not: what an update does to unset fields, whether status transitions are validated, and whether subtask creation requires an existing parent are all unstated.

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 task_id, parent_task_id, title, and the rest; the baseline of 3 applies. The description's gloss on verify_cmd ('names HOW the item is proven done') adds intent but not syntax, and its create-vs-update rule repeats the task_id 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 pair and resource ('Create or update one checklist item in a session's task tree') and immediately disambiguates the two modes via 'Omit task_id to create; pass task_id to update.' It also names the sibling goal_add and the condition that distinguishes them, so an agent can route without opening 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?

Explicit when-to-use ('call at the START of a tracked piece of work'), when-not ('ignore unrelated casual chat'), and the alternative for the cross-session case ('use goal_add on the board instead'). This is a full routing rule, not an implication.

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 no annotations, the description carries the full behavioral burden; it does disclose the most important trait — permanence and irreversibility ('This action cannot be undone'). It omits other relevant behavior: whether deleting a missing ID errors, whether removal cascades to related entries, and any permission requirements.

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 immediately followed by the destructive consequence. Every sentence earns its place with no filler.

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 one-parameter, no-output-schema delete tool, the description covers the action, the input target, and the critical irreversibility warning. Only edge-case behavior (not-found handling, side effects on related entries) is unaddressed, which is 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?

Schema coverage is 100% and the single 'id' parameter is already documented as 'The context entry ID to delete'. The description's 'by ID' adds no syntax, format, or lookup detail beyond the schema, 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?

The description states a specific verb and resource ('Permanently delete a context entry by ID'), which is unambiguous and easy to distinguish from read-oriented siblings like ctx_get or ctx_search. It stops short of naming a sibling (e.g., suggesting ctx_update as the non-destructive alternative), so it is clear but not sibling-differentiating.

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 this only when you are sure the entry should be removed' gives a weak precondition for use and implicitly warns against casual deletion. However, it names no explicit alternative (such as ctx_update for modification) and gives no guidance on when deletion is the wrong choice versus another tool.

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?

No annotations exist, so the description carries the full behavioral burden. It discloses the extra return fields (lifecycle, atomic, quality_score, valid_from, valid_to), which is genuinely useful, but says nothing about what happens on a missing/invalid ID, permission requirements, or that this is a non-mutating read. Adequate but with real gaps for a no-annotation 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?

Three sentences, front-loaded with the core action, then the usage condition, then the return payload. No redundancy or filler.

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 usefully enumerates the notable return fields, and a one-param getter needs little more. The main omission is error/not-found behavior, which an agent would likely want.

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% with a single documented parameter, so the schema already carries the semantics and the baseline is 3. The description only restates "exact context ID" without adding format, type, or lookup constraints.

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 ("Get a single context entry by its ID") and scopes it to a single record. It contrasts implicitly with retrieval-by-search via "single" and "exact context ID," but never names the sibling tools (ctx_search, ctx_list) it differs from.

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 this when you already know the exact context ID you want to read" gives a clear selecting condition and implies the when-not case (when you don't know the ID). It stops short of naming the alternative tool an agent should fall back to.

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 no annotations, the description carries full behavioral burden, and it does disclose meaningful traits: the exact components probed, a 30-second server-side in-memory cache (i.e., results may be stale by up to 30s), and the returned shape with the ok|degraded|fail status domain. It omits any note about auth/permission requirements or whether it is strictly read-only, which would matter for a prod-facing probe.

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 sentences, front-loaded with the action and followed by scope, caching behavior, and return shape. The trailing 'from MCP clients' is slightly redundant, 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 zero-parameter diagnostic with no output schema, the description supplies everything an agent needs: what is checked, the caching/staleness caveat, the return keys, and the status enumeration. Nothing essential is missing.

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

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

The tool takes zero parameters and the schema is empty with 100% coverage, so there is nothing for the description to clarify. Baseline 4 applies; no parameter guidance is needed or missing.

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 ('Run the deep health probe') and scopes it as deep vs. shallow by enumerating exactly what is probed (DB, Elasticsearch, embedding, LLM, schedulers). It does not explicitly distinguish itself from the sibling ctx_stats, which an agent could plausibly confuse with a health probe.

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 clear context for use ('ad-hoc prod health checks from MCP clients'), which tells the agent this is an on-demand diagnostic rather than a routine data call. It offers no exclusions or named alternative (e.g., when to prefer ctx_stats instead), 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?

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a safe read, but it does not explicitly state read-only semantics, default ordering, or pagination behavior — the latter is only inferable from the schema's limit/offset fields.

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 the primary action front-loaded and the usage context second. No filler, though it is on the terse side.

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 8-parameter list tool with no annotations and no output schema, the description covers purpose and filters but says nothing about the shape of returned entries, default result ordering, or pagination semantics. It is adequate but leaves gaps an agent would want filled.

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 description names four filter axes (workspace, project, type, tag) but omits scope, memoryKind, limit, and offset, adding little beyond what the schema already documents.

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

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

The description gives a specific verb+resource ('List context entries') and enumerates the filterable dimensions (workspace, project, type, tag). It implicitly distinguishes itself from ctx_search with 'without a search query', though it never names that sibling explicitly.

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 states the use case: browsing existing contexts by filter rather than searching. The contrast with a query-based tool is implied but there is no explicit when-not-to-use or naming of ctx_search as the alternative.

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 no annotations provided, the description carries the full behavioral burden. It discloses that loaded tools become callable without reconnecting, that some MCP clients need a tool-list refresh, that direct calls work even if tools/list does not show them, and that CONTEXT_MCP_TOOL_PROFILE=full loads everything upfront. It does not cover auth, idempotency, or return behavior, but it is substantially informative.

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 front-loads the core action before moving to the "all" shortcut and client-refresh troubleshooting. The troubleshooting sentence is long but earns its place by explaining a likely failure mode and concrete alternatives.

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 that mutates the session's available toolset, the description covers the operation, the special "all" value, client visibility caveats, and two fallback paths. It does not describe return values or invalid-group errors, but no output schema exists and the critical operational context is 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 description coverage is 100%, and the single required parameter already documents group names, examples, and the "all" special value. The description repeats that group names come from ctx_tool_groups and that "all" loads every remaining tool, but adds no syntax or format 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 states a specific verb and resource: "Load one additional group of ContextQ tools into this session." It distinguishes the action from the sibling ctx_tool_groups by explaining that group names come from that listing tool, so an agent can tell which tool loads versus lists groups.

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 tells the agent to get group names from ctx_tool_groups and explains that passing "all" loads every remaining tool. It also gives clear fallback behavior for clients that do not refresh their tool list. It stops short of an explicit when-not-to-use condition, but the 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?

With no annotations, the description carries the full burden and does so well: it discloses the LLM extraction step (durable facts only, skipping chit-chat), the shared kNN-dedup + diff + create/update/archive pipeline, the async threshold behavior, the { jobId, statusUrl } response and the need to poll ctx_ingest_status, plus dryRun's non-persisting semantics. This is rich operational context well beyond the schema.

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

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

Purpose and sibling relationship are front-loaded, and the three short paragraphs are dense with useful detail rather than filler. There is mild redundancy in the async explanation, which repeats what the 'async' parameter description already states.

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

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

With no output schema, the description compensates by describing both response shapes (inline full result for short conversations, { jobId, statusUrl } for async) and the polling requirement. Nothing an agent needs to call it 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?

Schema coverage is 100%, so the schema already documents all nine parameters; the description's explanations of subjectId scoping, dryRun, and async largely restate the schema descriptions rather than adding new syntax or constraints. Baseline 3 is appropriate 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 compound verb (extract and save durable memories) and its input resource (a raw multi-turn conversation), and explicitly frames itself as the 'turn-aware sibling of ctx_ingest', letting an agent separate it from the ingestion tool without opening either schema. Scope and output (deduped atomic contexts) are both named.

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 usage conditions: use subjectId to scope memories to a single end-user, use dryRun to preview, and how async selection works. It clearly explains the relationship to ctx_ingest but does not state when NOT to use this tool versus that sibling, so it falls short of full routing 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?

With no annotations, the description carries the burden well: it discloses that a backend judge runs asynchronously and returns atomic/quality_score/lifecycle, and that scope/lifecycle/memoryKind have backend defaults when omitted. It omits permissions/auth requirements and duplicate-handling behavior.

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

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

Purpose is front-loaded and each sentence carries information (types, triggers, defaults, response fields). The bilingual trigger list is slightly verbose but plausibly earns its place for matching.

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 usefully explains return fields (atomic, quality_score, lifecycle) and default behavior for optional params on a 13-param mutation tool. It still lacks error/validation and permission context.

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 all 13 parameters, including lifecycle, valid_from/valid_to and memoryKind. The description only restates the bi-temporal/maturity framing, adding little 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?

States a specific verb and resource ('Save a new context entry') and enumerates the entry types it accepts. It implicitly distinguishes itself from ctx_update via 'new', but never names a sibling, so it falls short of full 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?

Gives explicit when-to-call ('whenever work-relevant info should persist across sessions') plus when-not ('ignore unrelated casual chat'), reinforced with concrete trigger phrases in two languages. This leaves almost nothing to inference, though it does not name a sibling alternative.

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 no annotations, the description carries the full burden and largely meets it: it discloses the hybrid ranking approach, the effect of include_archived (surfaces retired notes), and the return fields (lifecycle, quality_score, matched_chunk). It omits auth/permission requirements and pagination semantics, so it isn't fully transparent.

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 and the whole thing is a tight four sentences. The second sentence ("find, remember, or look up") partly restates the first, a minor redundancy, but nothing else 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 17-parameter tool with 100% schema coverage and no output schema, the description covers the essence plus the key non-obvious flags and the return field shape. It leaves newer features (include_trace_events, epistemicMin tiers, memoryKind filtering) entirely to the schema, which is acceptable given full coverage but not fully self-contained.

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 documents all 17 parameters and the baseline is 3. The description adds light rationale beyond the schema (legacy ranking for lifecycle_boost=false, surfacing retired notes for include_archived), so it earns slightly above baseline.

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 (search/recall) plus resource (saved knowledge and memories), names the mechanism (hybrid full-text + semantic), and positions itself as "the default tool for 'what do I know about X'" — implicitly distinguishing it from save/get/list siblings. An agent can tell what this does and roughly where it fits without opening a 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 clear triggering contexts ("find, remember, or look up existing knowledge by keyword or phrase") and even per-parameter usage advice (chunk_search=false, lifecycle_boost=false, include_archived=true). It does not name explicit alternatives among the many ctx_* siblings or state when NOT to use it, 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?

No annotations are provided, so the description carries the full behavioral burden. It helpfully defines orphan_rate ('notes with no tags and no inbound references') and enumerates what the aggregate contains, but it never states that the operation is read-only, nor describes auth/rate-limit behavior. Decent but incomplete for an unannotated 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?

Two sentences, front-loaded with the concrete output enumeration and followed by the usage statement. Every listed metric earns its place by describing the return payload. Slightly list-dense but no wasted prose.

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 usefully compensates by enumerating the returned fields (totals, breakdowns, recents, orphan_rate). For a zero-parameter aggregation tool this is close to complete, though it omits return format and read-only confirmation.

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 per the rubric the baseline is 4. There is nothing for the description to clarify beyond the schema, and it correctly adds no spurious parameter detail.

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 ('Get aggregate statistics') and resource, then enumerates the exact metrics returned (totals, breakdowns by workspace/type/tag, recently updated, orphan_rate). This is far more specific than a generic 'get stats'. It stops short of explicitly distinguishing itself from the similarly overview-oriented sibling ctx_health, so it earns 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?

Gives clear when-to-use guidance: 'Use this for an overview of what is stored and to spot disconnected knowledge.' That maps the tool to two concrete scenarios. It offers no exclusions or explicit alternatives (e.g., how it differs from ctx_health or ctx_list), so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose the return payload in detail (group name, one-line purpose, member tool names, how many are already loaded, and the load mechanism). It implicitly signals a read-only listing operation, though it does not explicitly state safety, permissions, or side effects.

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

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

Purpose is front-loaded in sentence one and the key action ('search here first') in sentence two. The example enumeration (code-graph lookup, relay handoff, etc.) is somewhat list-heavy but genuinely aids discovery of unloaded tools.

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 and no annotations, the description fully compensates by describing exactly what is returned and how to act on it (load a group via ctx_load_tool_group). Nothing an agent needs in order to call this 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter surface for the description to clarify, and schema coverage is effectively 100%.

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 ('List') and resource ('additional groups of ContextQ tools not loaded in this session by default'), and immediately differentiates itself from all siblings as a meta-discovery/index tool. An agent can tell it apart from ctx_search or ctx_list without opening any schema.

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

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

It gives an explicit trigger condition: 'Search here first if a ContextQ tool you expect ... is missing from your current tool list.' It also names the follow-up sibling tool (ctx_load_tool_group) and the action to take, leaving nothing to inference.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses partial-update semantics ('only the provided fields are changed; omitted fields remain unchanged') and that archiving is possible, but says nothing about permissions, error behavior on a bad id, idempotency, or side effects of the memoryKind judge lock.

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 sentences with no redundancy. The core mutation semantics are front-loaded, and each sentence adds a distinct piece of information (partial update, use cases, temporal/lifecycle fields).

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 13-parameter mutation tool with no annotations and no output schema, the description covers the essentials an agent needs: what is updated, partial-update behavior, and how to archive. It falls short only on failure modes and permission requirements.

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 all 13 parameters, setting a baseline of 3. The description exceeds that by adding conceptual meaning: lifecycle maps to 'maturity' and valid_from/valid_to map to 'bi-temporal validity', helping an agent reason about those fields.

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 ('Update an existing context entry'), and the word 'existing' implicitly separates it from the create-oriented sibling ctx_save. However, it never names an alternative tool, so the differentiation is inferred 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?

Gives concrete usage cases: 'correct, append to, reclassify, or retire (archive) an existing entry.' That is clear when-to-use guidance, but no when-not-to-use conditions or explicit routing to siblings (e.g. ctx_save for new entries) are provided.

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 no annotations, the description carries the full behavioral burden and does well: it explains progressive elaboration (title-only, draft status for vague nodes), that a partial brief is rejected at the schema level, and that a work_item without a brief receives a `hint` containing the template. It does not disclose permissions, idempotency, or the shape of the response, which keeps it below 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?

The critical action and the 'only title required' rule are front-loaded, and every later sentence adds operational detail. The long trigger sentence with multi-lingual example utterances is heavier than typical but the examples are functional for matching, so the cost is justified rather than 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 16-parameter create tool with no annotations and no output schema, the description covers the core workflow well and flags the side behavior (hint generation) an agent would otherwise miss. It stops short of describing what is returned (e.g. the new node id) or permission requirements, which are the remaining 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 description coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains the mental model behind only-title-required, the draft default for vague nodes, and the consequence of omitting brief. The restating of kind/status/origin values adds little beyond the schema, but the progressive-elaboration framing is real added value.

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 sentence gives a specific verb+resource ('Add a node to the goal graph') and immediately frames it as a progressive-elaboration create operation, which cleanly separates it from read/advance siblings like goal_list, goal_frontier, and goal_advance. An agent knows exactly what this tool produces 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 an explicit trigger ('when a user asks you to remember or hand off a piece of work for later'), concrete example utterances, and an explicit exclusion ('Only call when the request is genuinely about work to track; ignore unrelated casual questions'). This is a rare case where when-to-use and when-not-to-use are both stated, so the only missing element is a named alternative tool.

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 no annotations, the description carries the full behavioral burden and does disclose two meaningful invariants: leaf->done REQUIRES real evidence (no-self-certification) and parent status rolls up automatically. It does not cover permission/auth needs, idempotency, or what the mutation returns, so it falls 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-loads the action and the critical evidence rule before the trigger list, with no filler. The multilingual trigger list is long but earns its place for routing; minor slack keeps it below 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 10-parameter mutation tool with no output schema and no annotations, the description supplies the essential operational rules (evidence gate, rollup, trigger scope). Remaining gaps like partial-payload and external_ref merge behavior are left to the schema, which documents them adequately.

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 all 10 parameters (including the note, payload merge, and status enum semantics). The description reinforces the evidence requirement for leaf->done but adds little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Advance a node's status') and immediately scopes it with the rollup and evidence rules. An agent can distinguish it from goal_add/goal_list/goal_frontier 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 an explicit trigger condition with concrete utterance examples ('xong rồi', 'done X', 'mark done'), plus a clear when-not rule ('Only call when the report maps to a tracked board item; ignore unrelated casual chatter'). This is exactly the routing guidance an agent needs.

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 no annotations, the description carries the full burden and does well: it discloses the return shape (GoalNode[] with depsIn/depsOut as [{nodeId, kind}]) and a meaningful behavioral nuance that nodes with externalRef.blocker are waiting on external events. It doesn't cover pagination or limits, but for a read tool the disclosure is substantial.

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 definition before qualifiers, and every clause (role/run_id scoping, return shape, blocker caveat) earns its place. The single long sentence is 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?

With no output schema, the description correctly compensates by naming the return type and its fields. The blocker caveat adds operational detail an agent needs. Only minor gaps (pagination/limits) remain for this zero-annotation 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces owner_role ('optionally for a role') and objective_run_id ('scoped to one objective_run_id') but ignores project_id entirely, adding nothing 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?

The description defines a specific, non-obvious concept ('the ready-frontier') and states the exact semantics: nodes whose blocking dependencies are all done. It effectively distinguishes the tool from siblings like goal_list and goal_advance by answering 'what can I start NOW'.

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 phrasing 'what can I start NOW' makes the use case clear, and the externalRef.blocker note tells the agent when a frontier node should NOT be treated as runnable. It does not, however, explicitly contrast this tool with goal_list or other goal siblings, leaving the routing decision partly 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?

With no annotations, the description carries the full burden and does disclose real behavior: a COMPACT default view, done nodes omitted unless include_done is true or a status filter is given, and the option to pass view="full". It omits pagination, result caps, and any auth/permission notes, which are relevant for a graph-listing 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?

Front-loads the core action, then adds one dense sentence covering return shape, default filtering, and the escalation path to goal_get/full view. The parenthetical field list is long but earns its place by preempting a schema lookup.

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 7-param read tool with no annotations and no output schema, the description compensates well by describing both the default compact payload contents and when nodes are excluded. Remaining gaps (pagination/limits, ordering) are minor but real.

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 meaning beyond the schema: it lists exactly which fields the compact view returns, explains the view default's effect on payload/brief, and clarifies the provenance of objective_run_id (from goal_set_objective/goal_get/goal_decompose).

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 goal nodes, filtered') and immediately enumerates the read modes (your lane, a status column, all milestones, one objective's run). It also explicitly names the sibling it is not, telling the agent to call goal_get for a single node's full payload.

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 when-to-use contexts (reading the graph by lane, status, milestones, or objective_run_id) and routes single-node reads to goal_get. It does not mention goal_frontier, which is the closest sibling, so the alternative coverage 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.