Foremerge

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

Despite annotations only stating non-read-only/non-idempotent, the description goes far beyond them by disclosing that Foremerge re-checks every gate, that a failed gate changes nothing and returns named error codes, that success writes refs/foremerge/accepted/<changeset_id>, and that overriding gates via MCP is refused. This is comprehensively transparent about side effects and failure 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?

The description is dense but every sentence carries load-bearing information: purpose, sequencing, gate criteria, side effects, error behavior, and override policy. The most important usage guidance is front-loaded, and the gate details are grouped logically.

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 tool with no output schema, the description fully explains preconditions, gate checks, success effects, failure modes, error identifiers, and the boundary of what MCP can do. An agent has enough to decide whether to call it and what to 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 already covers both parameters fully, so the baseline is 3. The description adds meaningful semantics for git_ref by explaining its fallback resolution order (publication ref, then worktree HEAD) and the constraint that it must resolve to the current worktree HEAD, which is not 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?

The description states a specific verb and resource ('Accept a ChangeSet as done') and immediately names the higher-level purpose ('so other agents may build on it'). It also contrasts with record_commit, which is the later step once work lands, so an agent can distinguish this from sibling tools.

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 the tool ('after run_verification passes'), when not to use it yet ('use record_commit later'), and how to handle conflicts via resolve_conflict and discard_work. It also tells the agent that gate overrides are refused over MCP and a human should be consulted, which is actionable 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?

Annotations already establish read-only/non-destructive, but the description adds substantial context: nothing is stored for a what-if check, persisted findings are limited to OPEN/COORDINATING conflicts, what-if findings get ephemeral eph_ ids and are not recorded, the state filter excludes ACCEPTED/COMMITTED/DISCARDED, and blocking is true when any finding is HIGH. No conflict with the declared annotations.

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

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

The purpose is front-loaded in the first sentence and follow-on sentences cover mode selection, state filtering, and return shape, each earning its place. It is dense and long, but for a two-mode tool with no output schema the length is largely justified 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?

With no output schema, the description carries the return burden and does so: conflicts (severity, explanation, evidence, suggested coordination step), checked_intents, blocking, and the active policy. Combined with the state-filter and ephemeral/persisted distinction, an agent has everything needed to call and interpret it.

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 beyond the per-field schema text by explaining how the parameters combine: intent_id alone lists persisted conflicts, intent text with scopes is a what-if check, and non-empty scopes with intent_id replace the intent's own scopes for that check only. That combination logic is genuinely additive.

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 — asking whether planned work collides with other agents' active work, before any change exists. It explicitly differentiates itself from publish_intent (same comparison, but for publishing) and from record_assessment/resolve_conflict (recording a decision), so an agent can route correctly 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?

Offers explicit timing ('use it while only planning', 'use this before publish_changeset and before run_verification') and names the alternatives to use when the goal is to record rather than check. Both invocation modes are framed with their selecting conditions (intent_id alone vs intent text vs intent_id plus replacement scopes).

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 far beyond annotations: discloses that claims never lock, that overlap still grants the claim and records a warning, that re-claiming renews the lease instead of adding a second claim, that the first claim moves the intent to CLAIMED, and that the result includes advisory_only: true. This fully describes side effects and semantics.

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 contributes: purpose, workflow position, locking semantics, renewal behavior, ownership/state constraints, and return payload. It front-loads the core purpose before diving into edge-case behavior.

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 stateful, advisory claim operation with no output schema and no idempotency hint, the description covers success behavior, failure/conflict handling, state transitions, expiry/renewal, and return contents. An agent has enough information to call it correctly and understand consequences.

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 input schema already documents all five parameters with 100% coverage, so the baseline is 3. The description adds value by clarifying that scopes must be those declared on the intent, by explaining the loose-by-name overlap matching, and by describing renewal behavior tied to lease_seconds. It does not add per-parameter syntax, but the schema already covers 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 states a specific verb and resource: claim semantic work on scopes of your own intent for a limited time. It also places the operation in a workflow (after publish_intent and record_assessment, before start_work) and contrasts it with start_work by saying claims are advisory and non-locking.

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 gives the when-to-use context: 'Use this after publish_intent and record_assessment, and before start_work.' It also states constraints (only the intent's owner, only while intent is INTENT/CLAIMED/IN_PROGRESS) and tells the caller to use the intent's declared scopes, which routes the agent away from inventing scopes.

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?

The description goes well beyond the destructiveHint annotation by specifying exact behavioral effects: setting intent to DISCARDED, releasing active claims, dismissing OPEN/COORDINATING conflicts, preserving history, and preventing resumption. It also discloses ownership and state restrictions, and notes the return value, giving the agent a complete mental model of 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?

The description is a single dense paragraph, but every sentence contributes meaningful operational detail: usage context, state effects, side effects, restrictions, return value, and the alternative tool. It is appropriately front-loaded and not padded, though slightly longer than minimal.

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-mutating tool with no output schema, the description covers all necessary context: valid states, ownership, side effects on claims and conflicts, irreversibility, event log behavior, and how to proceed instead. Nothing an agent needs to decide whether and how to call it correctly is missing.

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

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

Schema coverage is 100%, with each parameter (reason, agent_id, intent_id) already documented clearly. The description adds context that reason is recorded and that only the owner can discard, but this mostly reinforces schema information rather than supplying substantial new meaning. 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 clearly states the tool abandons one of your own intents with concrete examples (duplicate, work taken over), and explicitly contrasts it with resolve_conflict. It names the resource (intent) and the primary effect (set to DISCARDED), so an agent can distinguish it from siblings without ambiguity.

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 when-to-use guidance: for unfinished intents that are duplicates or taken over by another agent. It also names the alternative tool (resolve_conflict) and states when not to use this tool, such as ACCEPTED, COMMITTED, or already DISCARDED intents, plus ownership requirements.

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?

The description discloses significant side effects beyond the annotations: it snapshots the worktree, stores a fingerprint, starts the ChangeSet as PROVISIONAL, marks old ChangeSets SUPERSEDED, resets verification, and explicitly notes 'Git itself is not modified.' It also explains the return value, which is important because 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?

Every sentence carries distinct information: purpose, placement in workflow, snapshot/fingerprint behavior, file/symbol inference, state transitions, republish semantics, authorization constraints, Git safety, and return value. Despite its length, it is front-loaded with the most decision-relevant facts and contains 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?

The tool has 13 parameters, nested objects, and no output schema, yet the description covers return values, state transitions, side effects, ownership rules, and workflow ordering. Combined with the fully documented input schema, an agent has everything it needs to decide when to call and what to 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?

Schema description coverage is 100%, so the schema already documents all 13 parameters thoroughly. The description adds workflow context around files/symbols inference and defaults, but most of that is also present in the parameter descriptions. This meets the high-coverage baseline without adding substantial new per-parameter meaning.

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

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

The description opens with a specific verb and resource: 'Record a finished unit of implementation for your intent so it can be verified and accepted.' It clearly positions the tool in the workflow relative to siblings by saying 'after check_conflicts and before run_verification', leaving no ambiguity about what this tool does or how it differs from adjacent tools.

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

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

It gives explicit when-to-use guidance: 'once the change is committed in your worktree, after check_conflicts and before run_verification.' It also states preconditions and restrictions: only the intent's owner may publish, and only while the intent is in specific states. This is strong, actionable routing information.

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 flag readOnly=false, idempotent=false, destructive=false; the description adds substantial context beyond that: the intent is persisted with status INTENT, compared against every other active intent, and returns conflicts plus related_work with the asserted/why_surfaced semantics explained. It also front-loads the ordering constraint (before creating or editing any repository file).

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 and mostly tight, but the check_conflicts/'stores nothing' contrast is stated twice (once mid-paragraph, once in the closing sentence), which is redundant for a description this dense. Otherwise 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?

With no output schema, the description steps up to describe the return shape (int_ id, immediate conflicts, related_work with asserted and why_surfaced) and the full downstream coordination path. For a 7-parameter, nested-scope tool, 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; the description goes slightly beyond by tying 'the scopes it will change' to the conflict-detection mechanism, explaining why every scope must be declared. It does not add per-field syntax, but the schema already carries that, so the marginal semantics are the value-add.

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 ('Announce work you are about to do, and the scopes it will change') and names its position in the workflow relative to siblings (after register_agent, distinct from check_conflicts). An agent can distinguish it from claim_work/start_work/check_conflicts 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?

Gives explicit when-to-use ('the first write for a task you are committed to'), when-not ('while only planning, use check_conflicts, which stores nothing'), and the downstream sequence (record_assessment, then claim_work, then start_work). The alternative tool is named with the condition that selects it.

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

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

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 the failure mode (TARGET_DIVERGED), side effects on success (stores integration_commit, moves ChangeSet to COMMITTED, returns updated ChangeSet), and the non-destructive behavior toward accepted_commit. Since annotations only give false safety hints, this detailed behavioral context is essential and well provided.

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 earns its place: purpose, sequence, failure condition, success effects, preservation of accepted_commit, and a limiter on what the tool does not do. It is compact yet information-dense, with no 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?

The description is complete for invoking the tool correctly, covering prerequisites, ordering, error conditions, return value, and side effects. Even without an output schema or meaningful annotations, the agent has enough context to know when and how to call record_commit.

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 describes both parameters with 100% coverage. The description adds important relational context: git_ref must contain the accepted commit in its history or the call fails. This goes beyond the schema's basic definitions and helps the agent understand the meaningful constraint between changeset_id and git_ref.

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 records where accepted work landed after a merge, naming both the action and the resource. It distinguishes itself from siblings like accept_changeset by explaining it is used last, after acceptance and merging, and explicitly says it does not merge or push.

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 workflow guidance is provided: 'Use it last, after accept_changeset and the merge.' It also states the precondition that the commit must contain the accepted commit in its history, and clarifies that Foremerge does not merge or push anything itself, preventing misuse.

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.