Collide MCP

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description's 'Read-only' is largely redundant. It does add value beyond the annotations by disclosing the data source (live code graph), the freshness of in-flight work data, and a completeness caveat tied to briefing coverage.

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 tool is front-loaded with the trigger scenario before the output description, and the skip-condition is placed last where it belongs. The colon-fragment opening is slightly awkward, but every sentence carries information and nothing is 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?

No output schema exists, so the description takes on the burden of describing the return content — dependents at each level plus file, owner and in-flight work — and it does so completely. Combined with the usage and coverage caveats, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description only faintly gestures at them ('this one' for symbol, 'level by level' for depth) without adding syntax, defaults, or format guidance, so the baseline 3 applies.

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

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

States a specific resource and scope: every symbol that depends on this one, level by level, with each dependent's file, owner and in-flight work. This is clearly distinguishable from siblings like get_symbol and explain_code, and the phrasing 'what breaks if I change this' anchors the intent unmistakably.

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

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

Explicit trigger conditions ('Before renaming, changing a signature or deleting') and an explicit when-not ('skip it when the briefing's Coverage line says every dependent is already listed'), which also routes the agent to sibling get_briefing. Nothing is left to inference.

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

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

Annotations establish the safety profile (readOnlyHint=false, destructiveHint=false), so the bar is lower, and the description still adds real value: it discloses the concurrency guarantee ("two agents asking at once never get the same number"), the return format (zero-padded number), and the interaction with the create-file hooks. Gaps remain on reservation lifetime/expiry and what happens if a number is already taken, but this is well above the 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?

Three sentences, front-loaded with the core action and scope, then the when-to-use constraint, then the return shape. No filler; each sentence carries distinct information an agent needs.

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

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

With no output schema, the description correctly explains the return value (the padded number), and the mutating semantics are covered by annotations plus the reservation explanation. What is missing for a state-changing reservation tool is the failure/expiry behavior, but everything needed to make a correct call is present.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including that `sequence` may be a directory or a name. The description echoes the "named sequence" case and the zero-padding but adds no syntax or constraint detail beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a concrete verb and resource ("Reserve the next number in a sequence") and pins the scope with examples of what a sequence is: a migration, an ADR, a release. It also names the side effect (concurrency-safe reservation), so an agent knows exactly what it gets. No sibling in the list overlaps with this function, so disambiguation is not an issue.

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

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

Explicit when-to-use: "call this only for a number you need before writing, or for a named sequence." Explicit when-not: the hooks already claim a numbered file's number when you create it, so a plain file creation needs no claim. The alternative path (hooks on file creation) is named, leaving little to inference.

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

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

Annotations declare this is not read-only but non-destructive and not open-world; the description adds real behavioral context beyond them, disclosing that it installs hooks once for every repo on the machine and writes nothing into the repo, and that it returns an install command rather than performing everything silently. Missing permission/auth prerequisites and whether anything is written outside the repo.

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?

Effectively one dense sentence that front-loads the primary action and then the alternative mode. It is appropriately sized for a two-mode tool, though the parenthetical tool lists make it slightly heavy to scan.

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

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

For a two-parameter tool with no output schema, the description covers what both modes return and the machine-wide side effect, which is enough for correct invocation. Auth requirements and the exact shape of the returned files list are the only notable omissions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what mode="files" actually yields (protocol rules files and MCP configs to commit) and which tools need them, adding meaning beyond the schema's terser mode note.

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 ("Set up Collide for the agent tools on this machine"), names the concrete tools it targets, and explicitly differentiates itself from the sibling `setup` by describing what it returns relative to it. An agent can distinguish this from setup and from other siblings without opening a schema.

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

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

The description clearly splits the two modes: empty mode for the machine install, "files" for tools without hooks, listing which tools fall in each camp (Claude Code/Codex/Cursor/Hermes vs Windsurf/Cline/Copilot). It gives context but does not state when to prefer this over the sibling `setup`, despite referencing 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?

Goes well beyond the annotations: it discloses the one-shot firing behavior ('fires once into their next tool result and briefing'), the external side effect of creating a CRM task when connected (matching openWorldHint), and the return payload (tripwire id and expiry). This is rich, non-obvious behavioral context.

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

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

Front-loads the purpose, then layers mechanism, side effect, and return value in three tight sentences. The inline example is slightly long but earns its place by making the tripwire concept tangible.

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 five-parameter mutation tool with no output schema, the description covers purpose, firing behavior, side effects, and return values, which is nearly everything an agent needs. The only gap is the absence of when-not guidance relative to sibling memory/claim tools.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the baseline is 3. The description reinforces the paths/symbols trigger concept and mentions expiry in the return, but adds no syntax or format detail beyond the schema.

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

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

The description gives a concrete verb and resource: it creates a 'tripwire' on paths or symbols that warns the next editor. The concept is unmistakable and distinguishable from siblings like remember or claim, though no sibling is named explicitly to sharpen the contrast.

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

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

'Leave work unfinished safely' implies the trigger condition (you are stopping mid-task), and the example note makes the intent concrete. However, it never states when to prefer this over remember/claim or when not to use it, leaving the agent to infer the boundary.

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/destructiveHint=false, and the description's 'Read-only' merely restates that. It does add genuine behavioral context beyond the annotations: results are ordered oldest first, uncommitted work is included, and the output covers reverted attempts and their reasons — scope facts an agent cannot get from the hints 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?

Front-loaded with the motivating question, then a dense but earned enumeration of returned artifacts with no filler sentences. The single long clause stack is slightly heavy but each element describes real output content rather than padding.

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

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

There is no output schema, so the description carries the return-value burden and does so thoroughly — edits, intents, rationales, reverted attempts, notes, and uncommitted work — while also stating ordering. For a zero-required-param read-only tool, nothing an agent needs 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 description coverage is 100%, so all three parameters (path, symbol, repo_id) are already documented, including repo_id's fallback behavior. The description only restates the path/symbol pairing at a high level and adds no format or syntax 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 specific verb+resource — the history behind a path or symbol — and enumerates the exact payload (each edit with who/when/what, completed intents with rationales, reverted attempts, anchored notes). That content profile is unmistakably distinct from siblings like get_symbol (current code) or recall (agent memory), so an agent can route 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?

Usage is only implied by the framing 'Why the code is the way it is,' which signals the rationale/history use case, plus the scoping rule that omitting a symbol covers the whole file. There is no explicit when-not-to-use or named alternative (e.g., versus get_symbol or blast_radius), leaving the agent to infer the boundary.

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 carry readOnlyHint/destructiveHint, so the explicit 'Read-only' is largely redundant, but the description adds genuine behavioral context: the hook-deduplication rule, what the response contains, and the fact that supplying path/symbol expands the result into a blast-radius computation.

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 conditional constraint is front-loaded and every sentence carries information, but the description is dense and the trailing return-value list is slightly listy where a shorter clause would do. No wasted filler, though.

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 naming the return contents (summary lines, changed modules with exact signatures, anchored notes, live agents), and it covers usage gating, parameter behavior, and safety in one place. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by explaining the path+symbol combination semantics (symbol narrows the blast radius within path) and the purpose of repo_id's omission default, which the schema only partially conveys.

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

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

States a specific verb+resource (get the briefing = recent repo history) and enumerates its contents (who changed what, renames, hotspots, abandoned work, live agents). It is clearly distinguishable from siblings like recap/recall and even notes its overlap with blast_radius.

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 gating condition ('Only when no Collide briefing is in your context') plus an explicit when-not ('Where the hooks run... do not call this again for it'), and points to the path/symbol route for blast-radius work instead. Nothing about when to invoke 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered and the trailing 'Read-only' is largely redundant. The description still adds real behavioral context: it reads facts 'without opening the file', describes what data is surfaced (notes anchored to the symbol, check status), and explains the fallback behavior when symbol is omitted.

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 value proposition and what is returned, then the routing guidance. The first sentence is a long comma-chained list that borders on run-on, but every clause carries information and nothing is padding.

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

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

With no output schema, the description carries the burden of describing returns and does so thoroughly, including the module-wide case and the attached notes/check status. Minor gaps remain: nothing about a nonexistent symbol or error behavior, which is acceptable but keeps it short of a 5.

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

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

Schema description coverage is 100%, so all three parameters (path, symbol, repo_id) are already documented with examples and the omit-semantics for symbol and repo_id. The description restates the symbol-omission behavior but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (get one symbol's facts) and enumerates exactly what comes back: signature, parameters, calls, span, hash, anchored notes, and repo check status. It also carves out the module-wide variant when symbol is omitted, so an agent can distinguish it from blast_radius and get_briefing 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 an explicit trigger ('use it when a briefing lacks a fact') and names the alternative plus its selecting condition ('use blast_radius for who depends on it'). Both the when and the when-not are stated, leaving nothing to inference.

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

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

Adds real behavior beyond the annotations: unacknowledged messages repeat on every response, and the call returns the still-pending messages. The idempotent/non-destructive/closed-world profile is already covered by annotations, but the repeat semantics and return content are new information the agent could not get from structured fields.

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

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

Two sentences, front-loaded with the action and effect, then the operational rule. Every clause earns its place: action, trigger, consequence, return 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?

With no output schema, the description wisely states the return ('the messages still pending'), and the annotation set covers the safety profile. Only minor gaps remain, such as behavior for unknown or already-acked ids, so it is complete enough to call 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 baseline is 3, but the description adds meaning about the ids parameter's provenance and timing ('from messages_pending once you have acted on them'), which the schema only states as 'Message ids from messages_pending.' repo_id semantics remain schema-only.

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 ('Mark messages ... as handled') plus the effect ('so they stop arriving'), which is precisely distinguishable from the sibling send_agent_message. An agent knows immediately this is the acknowledgement side of the agent inbox loop.

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

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

Gives an explicit trigger and prerequisite: 'pass the ids from messages_pending once you have acted on them', and a consequence for skipping it ('Unacknowledged messages repeat on every response'). It stops short of a when-not case (e.g. what to do with an id you cannot act on), so 4 rather than 5.

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

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

Annotations already declare destructiveHint=false, and the description reinforces and sharpens this with an explicit merge rule ('keeping both sides' work; never by deleting either'), which tells the agent exactly what is and isn't allowed. It also discloses the two-phase claim-then-resolve workflow and the return content ('claimed reconciliations and how many stay open'), adding real context beyond the annotations.

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

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

The trigger condition is front-loaded, followed by the merge rule and the resolve step, so an agent can act from the first clause onward. It is a little dense and conversational, but nearly every sentence carries actionable information, so it stays well-structured.

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 stating what is returned ('the claimed reconciliations and how many stay open') and by covering the full trigger/workflow for both parameters. It is essentially complete for an agent to invoke it correctly, with only minor room to name the non-collision path.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: it explains that resolve carries ids of reconciliations already merged and verified, and that calling with resolve=[id] is a second invocation after tests pass. That workflow-level semantics raises it above baseline.

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

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

The description states a specific two-mode behavior: claim open collisions so they can be merged, and later resolve them with resolve=[id]. The verb+resource (claim/merge reconciliations) is clear and concrete. It stops short of explicitly distinguishing itself from the sibling 'claim' tool, so it is strong but not maximally differentiated.

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

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

It gives an explicit trigger ('When a response says two agents' work collides (reconciliations_pending)') and a clear follow-up condition ('After the merge passes the tests, call again with resolve=[id]'), which sequences the two calls correctly. No explicit when-not guidance or named alternative is given, keeping it just below top marks.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds non-obvious behavior: empty query returns the most recent, results are ordered newest first, and each note comes back with anchor, confidence and a staleness flag. It does not discuss rate limits or result truncation, so it falls short of a 5.

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

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

Front-loads what the tool does and follows with the usage constraint, so the important routing information comes first. It is dense and slightly overpacked — three ideas separated by semicolons — 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?

There is no output schema, and the description compensates by naming the returned fields (anchor, confidence, staleness). Combined with the ordering, empty-query behavior, and the note-creation sibling, an agent has everything needed to call and interpret this 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 description coverage is 100%, so tags, limit, query and repo_id are already documented, including the empty-query fallback and the repo_id omission default. The description adds only the 'newest first' ordering, which the schema does not state — enough to hold the baseline of 3 but not to exceed it.

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 (search the team's saved notes) plus the matching mechanism (by text and tags) and ordering (newest first). It also names the sibling tool that produces the data (remember), so an agent can place it in the workflow without opening a schema.

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

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

Explicitly says when NOT to use it — the hook briefing already carries notes anchored to the code you touch — and when to reach for it instead: searching beyond those anchors, before re-deciding something the team may already have settled. That is a clear when/when-not/alternative triad.

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, destructiveHint=false, and openWorldHint=false, so the repeated 'Read-only' line adds little. However, the description does disclose the return granularity ('one entry per session') and a dashboard link, which is real behavioral context not present in any structured field.

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

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

Three tight sentences, front-loaded with the metric inventory before the usage hint and the return note. The 'Read-only' sentence is mildly redundant against the annotations, but nothing is padded or buried.

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

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

With no output schema, the description usefully compensates by naming the fields returned and the per-session granularity plus dashboard link. Combined with 100% schema coverage on the two optional params, an agent has enough to call it correctly; only minor gaps (auth/connection prerequisites) remain.

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 (days, repo_id) are already fully documented, including the 90-day cap and the repo_id format/default. The description only hints at repo scoping with 'in this repo' and adds no syntax or default detail beyond the schema.

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

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

The first sentence states precisely what the tool surfaces: per-session agent activity (edits, lines, tokens, model, cost, rationales, paths). That is a clear verb-plus-resource statement that resolves the opaque name 'recap'. It does not, however, explicitly differentiate itself from nearby siblings such as recall, remember, or get_briefing.

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 trigger phrasings: use it to answer 'what happened' or 'what did this cost', which maps directly onto likely user intents. It offers no when-not guidance or named alternatives (e.g. recall for stored memory), so it stops short of full routing guidance.

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

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

Goes well beyond the annotations by disclosing non-obvious lifecycle behavior: anchored notes reach whoever touches that code, are marked stale when it is rewritten, decisions never go stale, and each agent's first write at a decision's location is held once with it. It also states the write returns ids. It does not explain what the destructiveHint=true annotation implies (retiring notes via supersedes is only documented in the schema), so this falls just short of a 5.

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

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

Three sentences, front-loaded with the core purpose and with the anchor and decision semantics following in logical order; every sentence carries information. It is dense with parenthetical examples, which slightly hurts scannability, but 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?

For a 7-parameter, zero-required mutation tool with no output schema, the description covers the important semantics (what to save, anchoring, decision behavior, returned ids). It omits supersedes/withdrawal semantics and batch `facts` handling, which are only described in the schema, but nothing critical to a correct first call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for anchor (path::symbol, file, or dir/, and who it reaches) and kind (decision requires an anchor and behaves differently). tags and supersedes are left to the schema, so it improves on the baseline without covering everything.

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

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

States a specific verb and resource ('Save a durable team fact: a decision, constraint or gotcha') and immediately excludes the wrong content type ('not code state'), which separates it from code-reading siblings like explain_code, get_symbol, recall and recap. An agent knows without opening the schema that this is the write-side of team memory.

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 conditional guidance: anchor notes that concern specific code, and the specific trigger 'When the human states a standing decision ("remove X", "never Y", "only Z")' routed to kind="decision" with an anchor. It also names when-not-to-use ('not code state') and ties decisions to the code they cover, so selection between plain notes, anchored notes and decisions is fully determined.

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 this as a non-read-only, open-world, non-destructive write. The description goes well beyond them: it discloses delivery timing ('arrives with their next tool result'), a contact-acceptance prerequisite for messaging arbitrary '@user' accounts, what the anchor recipient additionally sees (whether the code changed and whether tests passed since), and the return payload (message id and recipients).

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 nearly every sentence carries routing information that cannot be dropped. However, the routing rules are packed into a single dense paragraph with nested clauses, which makes scanning harder than it needs to be.

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

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

For a write tool with no output schema, the description covers routing modes, defaults, prerequisites, delivery behavior, and the shape of the response. An agent has everything needed to call it correctly without opening any other resource.

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 meaning the terse schema fields lack: how `to`, `anchor`, and `hub` interact, the default behavior when neither is supplied, that a new hub name combined with 'to="@a, @b"' starts a hub, and that repo_id defaults to the session's repo.

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: 'Send a message to teammates' agents.' It further distinguishes itself from siblings by naming the CLI equivalent (`collide message`) that needs no tool load, so an agent can tell this apart from connect_agents or inbox_ack at a glance.

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

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

Explicit routing decision tree: with neither `to` nor `anchor` it broadcasts to agents working in this repo whose files are named (or everyone if no code is named); `to` targets one account; `anchor` targets whoever has an open intent on or recently edited that code. It also names the alternative path (`collide message` in a shell). Nothing is left to inference.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing that nothing is written into the repo, that old per-repo .collide/ hook files are removed and staged for the user to commit, and that the machine is linked to the account. The staged-removal detail reconciles the seemingly destructive file deletion with destructiveHint=false.

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

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

Front-loads the core action and the imperative to run the returned command, then packs install/removal/return details efficiently. Slightly dense but each clause carries distinct information.

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

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

With no output schema, the description still explains the return ('Returns the command and what it installs'), the side effects, and the account linkage. An agent has everything needed to call it 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% and the schema already documents repo_id (git origin) and explains that mode is ignored. The description only implies the repo-root context and adds no parameter syntax or format beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Set up Collide on this machine') and enumerates exactly what the setup does: installs hooks for Claude Code, Codex, Cursor and Hermes, links the machine to the account. No sibling tool (blast_radius, claim, recall, etc.) overlaps, so the agent can identify it immediately.

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

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

Gives concrete usage context: 'once for every repo on it' and 'run it exactly as given, in a shell at the repo root.' It does not name alternatives or explicit when-not-to-use conditions, but no sibling competes for this job, so the guidance is clear without exclusions.

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