Foremerge

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

Annotations only say it is a non-destructive, non-idempotent write with no override; the description adds substantial context beyond that: it enumerates every gate re-checked, the exact failure error codes, that a failed gate changes nothing, and the state written on success (ACCEPTED status, accepted_commit pin, refs/foremerge/accepted/...). It also discloses that gate overrides are refused over MCP and must go to a human, which is critical behavior an agent could not infer.

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 the when-to-use rule before the gate detail, and nearly every clause carries load-bearing information (gate list, error codes, side effects). The gate enumeration is dense and slightly overlong, but not wasteful.

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

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

No output schema exists, yet the description states what is returned (the updated ChangeSet) along with state mutations and ref writes. Combined with the explicit failure modes and MCP override restriction, an agent has everything needed to call it correctly and interpret the result.

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%, with git_ref's defaulting and HEAD-resolution rules documented in the schema itself, so the description does not need to repeat them. The description adds only indirect meaning (the worktree must be clean and unchanged), leaving the baseline 3 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 ('Accept a ChangeSet as done') plus the downstream consequence ('so other agents may build on it'). It explicitly contrasts with the sibling record_commit, so an agent can distinguish the two 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 an explicit ordering rule: use this after run_verification passes, and use record_commit later once work has landed. It also names the sibling tools that clear blocking conditions (resolve_conflict, discard_work), so the agent knows how to unblock a failed accept.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, so the safety profile itself is covered; the description's 'nothing is stored' restates that but adds the useful nuance that findings get ephemeral eph_ ids and are not recorded. It also discloses the compared intent-status window (INTENT through VALIDATED, excluding ACCEPTED/COMMITTED/DISCARDED), the blocking-when-HIGH rule, and as_of_event semantics, which are genuinely beyond the annotations. However, these are largely framed as return-shape detail rather than deeper operational constraints, so it sits just above the annotated baseline.

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

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

It is long, but front-loaded with the core purpose and constraint before the mode and return-value detail, and each clause (timing, modes, status window, return fields) earns its place given there is no output schema. Minor redundancy between 'Read-only: nothing is stored' and the readOnlyHint annotation, and the trailing enumeration of return fields is dense.

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 returned fields (conflicts with severity/explanation/evidence/suggested step, checked_intents, blocking, ephemeral, as_of_event, active policy). Combined with the status-window and two-mode explanations, an agent has everything needed to call it correctly and interpret the result.

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 each parameter already has a rich description, including the intent-vs-intent_id rejection rule and the same-kind/operation semantics, so the baseline of 3 applies. The description adds the combination semantics — intent_id alone versus intent_id plus replacement scopes versus intent text plus proposed scopes — which is real value, but it largely mirrors what the schema's own parameter descriptions state.

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 states a specific verb and resource: ask whether planned work collides with other agents' active work, before any change exists. It explicitly positions itself against publish_intent (same comparison, but read-only, no stored change) and against record_assessment/resolve_conflict (for recording decisions). An agent can tell exactly what this does versus 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?

It gives concrete timing ('before publish_changeset and before run_verification, since conflicts are raised when the later intent publishes') and explains the two invocation modes: intent_id alone for persisted OPEN/COORDINATING conflicts, intent text plus scopes or intent_id plus replacement scopes for a what-if check. It also names the alternatives to reach for when the goal is to record a decision rather than detect a conflict.

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

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

Annotations only declare the read/write safety profile; the description supplies the substantive semantics — claims are advisory and never lock, overlapping claims still succeed but produce a recorded warning, the first claim transitions INTENT→CLAIMED, and re-claiming renews the lease rather than duplicating. It even discloses the return payload components, which is critical given there is no output 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 is front-loaded in the first sentence and every subsequent sentence carries non-obvious information (ordering, advisory nature, renewal, ownership, returns). It is dense — the third sentence bundles advisory semantics, conflict handling, and warnings — but no sentence is 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 mutating, non-idempotent tool with no output schema, the description covers the state machine, authorization constraint, the renewal idiom, the conflict-warning behavior, and the shape of the response. 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?

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning on top by explaining that symbol matching is loose and case-insensitive by name, and that re-claiming an existing scope renews the lease (the practical use of lease_seconds for long-running work). It does not restate the enum or the 60s–24h bounds, but the schema already covers those.

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?

Opens with a concrete verb+resource: registering an advisory claim on scopes of your own intent for a limited time. It distinguishes itself from siblings by naming publish_intent, record_assessment, and start_work as the surrounding sequence, so an agent knows exactly where this sits in the workflow.

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

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

Explicitly states when to use it ('after publish_intent and record_assessment, and before start_work') and what alternative behavior to expect ('Claiming a scope the intent already holds renews its lease instead of adding a second claim'). It also states the preconditions: owner-only, and only while the intent is INTENT, CLAIMED, or IN_PROGRESS.

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

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

The description goes well beyond the uninformative all-false annotations, disclosing that the message is appended to a durable log with status UNREAD, that it does not interrupt or control the recipient, that linking a conflict_id moves it from OPEN to COORDINATING, and that no MCP tool reads messages. It also states the return value includes the stored message and its msg_ id.

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

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

The description is longer than typical but every sentence carries distinct information: purpose, trigger, follow-up action, state transition, durability, non-interruptive nature, and return value. It is deliberately structured and front-loaded with the core operation, with no filler or repetition.

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 lacking an output schema, the description explicitly states what is returned. It covers the integration with sibling tools, the state change on conflict_id, the durable status semantics, and the limitation that only the CLI can read messages. This is a complete briefing for a tool with this complexity.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters. The description adds a bit of contextual meaning (e.g., conflict_id linking moves the conflict, eph_ ids are rejected), but most parameter semantics already appear in the schema, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Send a stored message to another registered agent,' and immediately states the purpose—'to agree how two overlapping pieces of work should coexist.' It also differentiates from siblings by referencing check_conflicts and resolve_conflict, clarifying this tool is for the message-sending step, not conflict detection or resolution.

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 guidance is given: 'Use it when check_conflicts or related_work shows a clash you need the other agent to act on.' It also explains the follow-up flow with resolve_conflict and names the message id, and notes that the recipient reads via CLI since no MCP tool reads messages. This fully covers when and how to use the tool relative to 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?

Annotations declare destructiveHint=true, but the description goes well beyond that: it states what specifically changes (intent set to DISCARDED, active claims released, OPEN/COORDINATING conflicts dismissed so they stop blocking the other party), that the event history is retained but the intent cannot be resumed, and that landed_ref does not imply verification ('still ends DISCARDED, not ACCEPTED'). It also discloses the return value. No contradiction with the destructive/readOnly hints.

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 organized by a 'Two cases' branch that makes the dense content scannable. It is longer than minimal—some explanation of state transitions and the landed_ref caveat could be trimmed—but virtually every sentence carries operational meaning.

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?

Covers all four parameters with their conditional usage, the post-call state of the intent and its claims/conflicts, the ownership and state preconditions, resume impossibility, and the return value. With no output schema, this is exactly the context an agent needs to call a destructive state-changing tool safely.

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 genuine semantics the schema does not: the conditional relationship between the parameters ('pass a reason' alone vs 'pass landed_ref as well'), and the consequence of landed_ref (commit checked and recorded but intent still DISCARDED). It does not restate the error codes, which the schema already carries.

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 ('Close one of your own intents') plus the condition that distinguishes it ('that you will not take through accept_changeset'). It also names the sibling it must not be confused with ('To agree that two intents can coexist, use resolve_conflict instead'), so an agent can route correctly 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 explicit timing ('Call it before you stop working, whenever the intent is still open'), two enumerated usage cases (abandoned work vs work that landed without a passing named check), and a hard exclusion with an alternative (resolve_conflict). Preconditions are spelled out: only the owner, and not once ACCEPTED, COMMITTED or already DISCARDED.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld=false, and the description reinforces this with 'Read-only.' It also adds meaningful behavioral detail beyond the annotations: accepted_commit is pinned at acceptance and never changed, and integration_commit is set by record_commit. No contradiction with annotations is present.

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 information-dense and well-structured: operation and target first, then what can be checked, then read-only status, then routing to alternatives. Every sentence earns its place, and no filler or redundant restating of the title appears.

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 full schema coverage and comprehensive annotations, the description fully covers what an agent needs: what the tool returns conceptually (status, fingerprint, provenance) and how to obtain an id. The absence of an output schema does not create a material gap because the description names the fields the agent should expect.

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 schema covers 100% of parameters with a clear description of id, so the baseline is 3. The description adds useful parameter context by explaining how to find an id: status lists qualifying ChangeSets and query_work shows each intent's latest one. This exceeds the schema's minimal id description.

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

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

The description uses a specific verb-resource pair: 'Read one ChangeSet by id', and clearly distinguishes it from siblings by stating what it is not for: 'Use get_intent for the work item itself.' An agent can tell this tool apart from get_intent, status, and query_work without inspecting 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?

It explicitly states when to use this tool: to check ChangeSet status, fingerprint, and commit provenance. It also names alternatives and when they apply, including get_intent for the work item, status for finding PROVISIONAL/VALIDATED/ACCEPTED ids, and query_work for each intent's latest ChangeSet.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description reinforces this with 'Read-only.' It goes beyond annotations by disclosing the return shape (conflict counts/ids, status enum, scopes, depends_on) and noting that severity requires check_conflicts.

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 dense sentences with zero filler. The core purpose is front-loaded, followed by return details and sibling routing. Each sentence contributes distinct value.

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 strong annotations and explicit sibling routing, the description covers the purpose, return contents, safety profile, and alternatives. No critical information an agent needs 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 schema already fully documents the single id parameter with format 'int_...'. The description mentions reading by id but adds no new parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('Read one intent by id') and enumerates exactly what is returned: owning agent, OPEN/COORDINATING conflict count and ids, status, scopes, and depends_on. It also distinguishes itself from query_work and status 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?

Provides clear when-to-use context ('before assessing someone else's related work') and explicitly routes to alternatives: query_work for searching by agent/status/scope and status for everything at once. This leaves little ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description reinforces read-only behavior and adds the detail of registration order, which goes beyond the annotations. It doesn't contradict annotations and provides useful context about the returned data.

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

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

The description is efficient with no fluff. It front-loads the purpose, then provides usage guidance in separate short sentences. Each sentence adds value: purpose, read-only/no-args, usage for coordinate_with_agent, and usage for status. No redundant 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?

Given the tool has no output schema, the description compensates by listing all returned fields and their order. It also covers a primary use case (finding agent ids) and mentions the alternative (status). For a simple read-only list tool, 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 has zero parameters and the schema is empty, so there is nothing to explain. The description explicitly notes 'takes no arguments', which is helpful confirmation. Baseline for 0 params is 4, and this description meets that.

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 clearly states the tool lists every registered agent with a specific set of fields (id, name, model, capabilities, worktree, Git branch/head, status). It distinguishes from siblings by noting it's a full listing, unlike status which focuses on active agents. The verb 'List' and resource 'registered agents' are explicit.

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

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

The description gives explicit guidance: use it to find agent ids before coordinate_with_agent, and use status for active agents alongside current work. This differentiates it from the status tool and provides a clear when-to-use and when-not-to-use scenario.

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?

Goes well beyond the annotations (readOnly=false, idempotent=false, destructive=false) by disclosing the state machine: the ChangeSet starts PROVISIONAL, the intent becomes PROVISIONAL, re-publishing supersedes the old ChangeSet and resets verification. It also states the important safety fact that Git itself is not modified, plus the STALE_CHANGESET rejection 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?

Dense but front-loaded: the first sentence establishes purpose, the second establishes workflow position, then behavior and preconditions follow. Every sentence carries information, though the description runs long and a reader must hold several state-transition facts at once.

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 output schema, the description covers preconditions, side effects, state transitions, and even the return payload ('the ChangeSet, including its chg_ id, fingerprint, and open_conflicts'). Nothing an agent needs to invoke 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 description coverage is 100%, so the schema already carries the parameter burden; the description's note that files and symbols are inferred only from uncommitted changes largely restates the schema's own wording. It does add the defaulting chain for worktree (registered worktree, then server CWD) and the fingerprint/base_ref resolution, but these are also documented in 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 ('Record a finished unit of implementation for your intent') and immediately positions it in the workflow relative to siblings check_conflicts, run_verification, and accept_changeset. An agent can distinguish it from get_changeset and publish_intent 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?

Gives explicit ordering ('once the change is committed in your worktree, after check_conflicts and before run_verification') and explicit eligibility conditions ('Only the intent's owner may publish, while the intent is CLAIMED, IN_PROGRESS, PROVISIONAL or VALIDATED'). It also names the alternative path for committed work, and covers the re-publish case that selects a different outcome.

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

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

Annotations only say non-readOnly, non-destructive, non-idempotent, closed-world; the description goes well beyond by disclosing the stored status INTENT, that the intent is compared against every other active intent, and the exact response payload (int_ id, immediate conflicts, warnings such as undeclared scopes or a symbol losing its class, related_work with asserted/why_surfaced). It also clarifies that this call is a persistent write, not a what-if.

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 its timing, then response shape, then the mandated follow-up sequence. It is dense but earns most of its length; the closing 'Use check_conflicts instead for a what-if check that stores nothing' largely repeats the earlier 'while only planning, use check_conflicts, which stores nothing'.

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 no output schema, the description supplies the missing return-value contract, the warnings taxonomy, the asserted-vs-candidate distinction, and the downstream call sequence. An agent has everything needed to call it correctly and act on the result.

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: conflict detection relies on the scopes list so all must be declared, and omitting them produces a warning. That connects the scopes parameter to observable output behavior rather than restating 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 (announce) and resource (intent, with the scopes it will change) and pins the moment in the workflow: first write for a committed task, after register_agent, before creating or editing repository files. It is clearly distinguished from the read-only alternative check_conflicts, which is named twice.

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 (about to do committed write work, before touching files), explicit when-not/alternative (while only planning, use check_conflicts since it stores nothing), and explicit ordering relative to siblings (record_assessment, then claim_work, then start_work). Little is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's 'Read-only' phrase is redundant but harmless. It adds genuine behavioral value beyond annotations by disclosing the result shape (joins intent to agent, claims, latest ChangeSet, dependent intent ids, and OPEN/COORDINATING conflict counts), array capping by limit, and the surprising default that with no filters it returns intents of every status including finished ones.

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 focused sentences with zero filler: purpose and examples, result shape and safety, default behavior and sibling routing. The most decision-relevant information (what it does, how results look) is front-loaded, and the sibling routing closes the description. Every sentence 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 complex query tool with no output schema, the description compensates well by describing the joined result shape, the capping behavior, and the unfiltered default. The exhaustive schema covers parameter semantics, so the only gap is exact output field names/types, which the narrative join description largely mitigates. Minor omissions like pagination details are covered by the limit parameter's schema description.

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%: limit, status, agent_id, and the nested scope object all have thorough descriptions, including the loose symbol-matching caveat. The description reinforces the semantic mapping of filters to questions (owner/status/scope) but adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Search intents by owner, status or scope') and illustrates the purpose with concrete questions ('who is changing this symbol, or which work still has open conflicts'). It also names the siblings it is not ('Use get_intent when you already have an id, and status for a grouped overview'), so an agent can distinguish it from confusable read-only tools 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?

The description explicitly routes the agent to alternatives with the triggering condition: 'Use get_intent when you already have an id, and status for a grouped overview of everything at once.' It also embeds usage signals via the example questions and states the default no-filter behavior, which tells the agent when this tool is appropriate versus when a narrower lookup is better.

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?

Goes well beyond the annotations: append-not-replace semantics (consistent with idempotentHint=false), no status mutations, an authorization constraint ('Only the intent's owner may assess it'), and the returned identifier (asm_). The non-destructive-to-conflict-state clarification is exactly the kind of context annotations cannot convey.

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

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

Front-loaded with purpose and organized so each sentence adds a distinct rule (ordering, append behavior, follow-up tools, ownership). Slightly long at six sentences, and 'Only the intent's owner may assess it' partly duplicates the agent_id schema text, keeping it just short of a 5.

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

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

Covers the full call lifecycle an agent needs: when to call, ordering relative to publish_intent and file changes, what the call does and does not mutate, authorization, and what is returned even though no output schema exists. Nothing material is missing 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, but the description adds real meaning by clarifying that the stored verdict is the agent's judgment about system-reported overlap rather than a restatement of it, and that the rationale must be checkable later. It does not add syntax or format detail beyond that.

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 what you concluded about one entry from related_work') and immediately frames the division of labor: the system reports overlaps, the agent decides their meaning. It is clearly distinguishable from siblings like check_conflicts, resolve_conflict and coordinate_with_agent, which are named as separate actions rather than folded into this tool.

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

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

Gives an explicit triggering condition and ordering ('Call this once per related intent, after publish_intent and before you change files') plus explicit routing to alternatives ('Act on the verdict with coordinate_with_agent, resolve_conflict or discard_work as needed'). The when-not is also clear: it does not open, resolve or dismiss conflicts.

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

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

The description discloses behavior well beyond the annotations: it validates containment by ancestor or content, names the failure mode TARGET_DIVERGED, describes the state transition to COMMITTED, and explains the returned provenance.integration.method. It also clarifies that accepted_commit remains unchanged, making the record show both verification and final landing.

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

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

The description is front-loaded with purpose and usage, then moves into validation, success behavior, and a clarifying caveat. Despite being fairly dense, every sentence contributes material information for correct invocation.

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, but the description covers the important return behavior: the updated ChangeSet and its provenance.integration.method. It also covers failure behavior and state changes, so an agent has enough context to call the tool correctly.

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

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

Schema coverage is 100%, so the two parameters are already documented. The description still adds meaningful semantics by explaining how git_ref is validated against the accepted commit or, after squash/rebase, against the candidate changes path by path using the merge base.

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

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

The description gives a specific verb and resource: recording where accepted work landed after merge. It clearly distinguishes this tool from accept_changeset and the merge step by saying to use it last, after accept_changeset and the merge.

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 explicitly states when to use the tool: after accepted work has been merged through ordinary Git or a pull request. It also states the key prerequisite and what happens when it is not met, failing with TARGET_DIVERGED, and clarifies that Foremerge does not merge or push itself.

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

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

Beyond the annotations, the description discloses important non-obvious behaviors: every call creates a new agent record even for a repeated name, a warning is returned when an active same-name/worktree agent exists, invalid worktree paths are rejected with INVALID_INPUT, and the response includes the agent plus warnings. These details are significant for correct invocation and are not visible from annotations alone.

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 dense but every sentence adds essential information: purpose, call timing, non-idempotence, warning conditions, validation behavior, and return value. It is longer than average but justified by the need to explain branching behavior and constraints. Slight restructuring could improve scannability, but nothing is wasted.

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

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

For a registration tool with no output schema, the description is remarkably complete: it covers lifecycle timing, idempotency caveats, validation failures, response contents, and relationship to other tools. An agent has enough information to call it correctly and interpret the result without additional investigation.

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 parameter descriptions already cover all four parameters at 100% coverage, providing a solid baseline. The description adds meaningful extra context for worktree by stating it must be inside the bound repository and is otherwise rejected, and clarifies that the worktree records Git branch and head. This goes beyond the schema without needing to repeat every parameter.

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

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

The description states a specific action ('Register yourself as a participant') and the concrete resource produced ('the agent id every other write tool needs'), immediately distinguishing it from sibling tools like list_agents or publish_intent. It clearly communicates the tool's central role in the workflow.

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

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

The description explicitly says to call it once at the start of each session and before publish_intent, providing clear ordering. It also warns about calling it again for the same name/worktree, which tells the agent when reusing the tool may not be appropriate. This is strong, actionable 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 only generic annotations (all false), the description carries the full burden and does so thoroughly. It discloses that agreement and message ids are not verified, that either party may resolve alone, the state transition to RESOLVED, the effect on both intents' acceptance gates, that code is not changed, failure conditions, and the return value. This goes far beyond what annotations provide.

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 information-dense yet every sentence earns its place: purpose, access constraint, safety warning, alternatives, side effects, failure mode, and return value. It is front-loaded with the core purpose and avoids filler, making it easy for an agent to scan and apply.

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 the tool's mutation semantics, the lack of an output schema, and minimal annotations, the description is complete. It covers the state change, failure conditions, constraints, and what is returned. An agent has enough information to invoke the tool safely and correctly without needing additional details.

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 four parameters in detail. The description adds some operational context (e.g., only a party may resolve, decision recorded under agent id), but it does not materially extend parameter meaning beyond what the schema's property descriptions already state. Baseline 3 is appropriate.

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

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

The description states a specific action ('Record an audited resolution decision') on a specific resource ('durable cfl_* conflict') and explains the goal ('so blocked work can proceed'). It also differentiates from discard_work, making the tool's unique role unmistakable.

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 explicitly tells the agent when to use the tool ('resolve only after the other party agrees'), which tool to use first ('Use coordinate_with_agent first'), and which alternative to choose instead ('discard_work instead when one side is simply dropping its work'). This is clear, actionable guidance with exclusions and 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?

Annotations provide no hints (all false), so the description carries the full burden and excels. It discloses side effects: may create generated files, moves state to VALIDATED or returns to PROVISIONAL, specific failure modes (STALE_CHANGESET, CHECK_FAILED), fingerprint requirements, and the registry timeout. This goes well beyond what annotations offer.

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?

Though lengthy, every sentence earns its place: purpose, usage timing, constraints, error conditions, state transitions, and return value are all covered. Front-loaded with purpose and usage, structured logically. 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 state-changing verification tool with error conditions and a return record, the description is complete. It covers prerequisites (fingerprint match), timing relative to siblings, error semantics, state outcomes, and the returned validation record. An agent can invoke it correctly without further info.

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 covers both parameters fully (100% coverage) with descriptions including format and state constraints. The description reiterates the changeset state requirement but adds no new parameter-specific meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific verb ('run') and resource ('one named check from the trusted Foremerge registry'), and explicitly differentiates from siblings by noting it is for verification between publish and accept, and that raw commands are not accepted. An agent can clearly identify this as the verification step.

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

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

Explicitly states when to use: 'Use it after publish_changeset and before accept_changeset; acceptance relies on this result, not on tests you report yourself.' Also says raw commands are not accepted, guiding away from any alternative that might accept free-form commands. No ambiguity.

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

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

Annotations cover the safety profile (non-read-only, non-destructive, non-idempotent), and the description adds state-machine semantics, ownership requirements, failure modes, and a follow-up dependency (check_conflicts before proceeding). This is rich behavioral context beyond what annotations provide.

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?

Every sentence carries unique information: purpose, timing, failure semantics, alternative tool, and return value. The state transition is front-loaded and there is 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?

Although there is no output schema, the description documents the return value (updated intent with open_conflicts count and ids) and directs the agent to check_conflicts next. Nothing needed to invoke or interpret the call correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (agent_id, intent_id) are already documented with their ownership and CLAIMED-state requirements. The description restates the ownership constraint but adds no new syntax or format detail, so 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 precise state transition (CLAIMED to IN_PROGRESS) with a specific verb and resource. It also explicitly names the sibling it is not (claim_work), so an agent can distinguish it 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 explicit timing ('after claim_work, immediately before you begin changing files'), explicit failure conditions ('fails in any other state, or if you do not own the intent'), and an explicit exclusion with an alternative ('does not create or renew claims; use claim_work for that').

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds value by stating it is a single consistent read and enumerating the exact content included, which helps the agent understand what the returned picture covers without an output 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?

The description is front-loaded with the core capability and content list, then adds usage guidance and alternatives. Every sentence serves a distinct purpose: what, safety, when, and what else to use.

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 no-argument read tool, the description completely specifies what the result includes, its consistency property, and when to call it. It also points to sibling tools for filtering and detail, so an agent has enough context to choose 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?

There are zero parameters, and the description explicitly says 'takes no arguments,' leaving no ambiguity. The schema fully covers parameter semantics, and the description reinforces that no arguments should be supplied.

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

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

The description states a specific purpose: get the whole coordination picture in one call, enumerating active agents, intents grouped by lifecycle status, claims, conficts, and ChangeSets. It also differentiates from siblings by point out query_work for filtering and get_intent/get_changeset for detail.

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

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

It explicitly says when to use it: orient at session start or before choosing work. It also names alternatives for other needs: query_work for filtering and get_intent/get_changeset for single item detail, making routing clear.

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