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

With no annotations, the description carries the full burden and delivers real behavioral context: the outcome is required for `done`, the `uncommitted` flag escalates collision warnings for other agents, and overlaps_omitted counts server-side cuts per level. It stops short of describing idempotency or what happens if the intent is already closed.

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

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

Purpose and the required-outcome instruction are front-loaded, and most sentences (collision warning escalation, overlaps_omitted) earn their place. The git-fact paragraph is somewhat verbose and duplicates schema text.

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?

Despite no output schema, the description explains the meaningful return signals (overlap excerpts and overlaps_omitted) and the required outcome artifact. It omits error/edge behavior for an already-completed intent, so it is strong but not fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, and the description's git-fact explanations largely restate them. Baseline 3 applies because the description adds no syntax or format detail beyond what the structured fields provide.

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

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

States a specific verb+resource ('Close out an intent') plus the triggering condition ('when work finishes or is abandoned'). It also names get_intent as the route to a full record, so an agent can place it among its 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?

Gives clear timing context (completion or abandonment) and points to get_intent for full records. It does not differentiate from close siblings like update_intent or mark_intent_landed, leaving a possible ambiguity about which tool ends the lifecycle.

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 must carry the behavioral burden, and it does state the key trait: 'Read-only; it records nothing.' However it is silent on other relevant behavior for a lookup tool, such as what happens when an 8-char prefix is not unique or how the full record is shaped.

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 scope, then the routing rationale, then the safety trait. No filler, and each sentence adds information the structured fields do not provide.

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 single-parameter read tool with no annotations and no output schema, the description covers what the tool does, when to reach for it, and that it is non-mutating. It stops short of covering prefix-ambiguity or lookup-failure behavior, which would fully close the 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 sole parameter's description already explains the id-or-unique-8-char-prefix semantics. The description repeats the same id/prefix detail without adding format or edge-case meaning (e.g., prefix ambiguity), so this sits at the baseline for well-covered schemas.

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 ('Fetch one intent's full record') plus the scope of what is returned ('the whole summary and outcome'). It also differentiates itself from the excerpt-bearing surfaces ('Overlap, context and list entries carry excerpts only'), so an agent can separate it from list_intents without opening 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?

Gives concrete triggers for calling it ('when the excerpt is not enough: an overlap you have to describe to your user, or a context outcome you want to read in full before starting'). Alternatives are implied via the excerpt-only surfaces rather than named directly, and there is no explicit when-not rule, so it falls just short of a full 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 provided, the description fully carries the disclosure burden: it explains q and overlaps are AND-combined, that omitting q is required for a clean collision check, that alert_level carries warn/fyi/nudge meanings, that same-branch hits are flagged as your own line of work, and that rows default to outcome_excerpt with detail='full' returning whole outcomes.

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 three-way branching before any detail, and nearly every sentence carries distinct information. It runs long with stacked clauses, but the density is earned rather than padded.

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

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

For a 14-parameter read tool with no output schema and no annotations, the description covers the return shape (alert_level values, outcome_excerpt vs full detail) and all decision-relevant modes, leaving no material gap for correct invocation.

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 93%, but the description adds genuine semantics beyond it: how q terms combine word-by-word and across filters, when match=any is warranted, that session='current' targets this session's own intents, and how detail trades excerpt against whole outcomes.

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 ('query in-flight and recent work across the team') and situates itself against a sibling by naming post_intent as the downstream action. An agent can distinguish list_intents from get_intent/post_intent 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?

Explicitly enumerates three distinct, mutually exclusive uses ('pick exactly one') with the exact parameter combinations that select each, plus exclusions ('no summary, no q', 'for a collision check, omit q') and the alternative (post_intent after the pre-planning check). Nothing is left to inference.

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

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

No annotations are provided, so the description carries the full burden. It clearly discloses that the tool is idempotent, never rewrites the completion record, and that providing commit SHAs is optional ('pass the commit SHAs if you know them; landing without them is fine and complete'). It also explains behavioral nuance ('the tree it cannot see is the one thing it cannot check for itself').

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 a single paragraph that front-loads the core action ('Record that work... is now in git'), then adds context about when and why to call it. Every sentence contributes meaningful information — 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?

Given that there is no output schema and no annotations, the description covers the tool's purpose, usage cues, behavioral traits, and parameter guidance comprehensively. The tool has low complexity (2 params, 1 required), and the description provides everything needed for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the purpose of the `commits` parameter in context ('if you know them. Omit if you don't — do not guess'), and emphasizes that the timestamp is the correction when commits are unknown. This added guidance justifies 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?

The description uses specific verbs ('Record', 'mark', 'landed') and clearly identifies the resource ('work an already-COMPLETED intent declared uncommitted is now in git'). It distinguishes this tool from siblings like complete_intent (which marks intent completion) and post_intent (which creates a new intent) by focusing on the post-completion git state update.

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 explicitly states when to call this ('the moment you learn it') and provides clear examples ('you committed and pushed that work yourself, or you can see in the tree that the work another session left uncommitted has since landed'). It explains the consequences of not calling it ('registry keeps warning', 'keeps re-telling the same story'), which strongly implies when it should be used.

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 bears the full burden and largely delivers: it explains that decision-type intents are stored complete, never collide, and need no complete_intent; that it returns the intent id to keep for the later outcome post; and describes the overlap alert levels warn/nudge/fyi and what each obliges the agent to do. This is exactly the behavioral context annotations would otherwise supply.

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 guidance is front-loaded well, but the second half becomes a dense run-on packed with field names and conditional alert logic. It is information-rich but strains readability; a few of the parentheticals could be trimmed without loss.

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-parameter mutation tool with a rich implied return shape and no output schema, this covers the important ground: kind inference, touch inference, the intent id, overlap warnings, context of prior outcomes, and the overlaps_omitted count. It stops short of describing the full response envelope or pagination/limits, but it is close to complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond by giving decision-specific semantics (outcome contents, no touches needed) and explains how touches should be inferred (repo-relative globs from the plan), adding operational meaning to the parameters rather than restating them.

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 ('Register') and resource ('what you are about to work on') with a concrete goal ('so other developers' agents can avoid collisions'). Clearly distinguishes this write/registration tool from the read-oriented siblings list_intents and get_intent.

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 says when to call it ('before starting any non-trivial coding task (anything touching more than a trivial fix)') and gives kind-specific guidance, including that decision should be posted 'the moment a debate settles' with no touches needed. Routes the agent to get_intent for full records, effectively naming the alternative for consuming results.

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 richly: it discloses the ~48h TTL expiry, that an id-only call renews the heartbeat, that stale globs cause silent collision misses, and that warn must be surfaced to the user. It also explains overlaps carry excerpts and that overlaps_omitted counts truncations — behavioral 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?

Front-loaded with purpose, then conditions, then returns, then the exclusion. Dense but every clause carries distinct information; the parenthetical asides make it read long, though little is truly expendable.

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

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

There is no output schema, so the description correctly compensates by explaining return values (overlaps, overlaps_omitted, excerpts) and directing to get_intent for a full record. Nothing needed to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: an id-only call still renews TTL and returns fresh overlaps, and touches replacement semantics drive collision checks. It goes past restating the per-field descriptions.

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 ('Update an in-progress intent') and scopes it to in-progress work, immediately distinguishing it from complete_intent and get_intent by name. An agent can tell it apart from its siblings without opening any schema.

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

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

Gives explicit triggers ('when the work changes shape', 'when work runs long'), the id-only heartbeat case, and a hard exclusion ('Never use this to finish work — call complete_intent for that'). Both when-to-use and when-not-to-use are spelled out.

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