Collide MCP

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the trailing 'Read-only' is largely redundant. What the description does add is behavioral context the annotations cannot: results come from the live code graph rather than a static grep, and each dependent is returned with file, owner and in-flight work. It still says nothing about cost, latency or auth requirements for a potentially deep traversal.

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 trigger conditions, then the payload, then the skip rule, in three dense clauses with essentially no filler. The only waste is the trailing 'Read-only', which repeats the readOnlyHint annotation.

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 read-only graph query with no output schema, the description carries exactly the missing information: what is returned (dependents by level with file, owner and in-flight work), how it differs from manual grep, and when the result would be redundant. Nothing needed to decide to call it is absent.

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 (repo_id, path, symbol, depth) is already documented in the schema. The description's 'level by level' loosely mirrors the depth parameter but adds no format or constraint detail, so the baseline of 3 applies.

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

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

States a concrete analysis operation (all dependents of a symbol, level by level) and frames it as the answer to 'what breaks if I change this'. It is clearly distinguishable from siblings like get_symbol, explain_code and get_briefing, and it even names the alternative approach it replaces (repo-wide grep).

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?

Names the triggering situations explicitly (before renaming, changing a signature, or deleting) and gives an explicit skip condition tied to a sibling's output ('skip it when the briefing's Coverage line says every dependent is already listed'). That is both when-to-use and when-not-to-use 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?

Beyond the annotations (which only say it is a non-read-only, non-destructive, non-open-world write), it discloses key behavioral traits: the concurrency guarantee ('two agents asking at once never get the same number'), the overlap with hook-driven auto-claiming, and the return format ('zero-padded like the files already there'). This is exactly the kind of context annotations cannot 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?

Three sentences, tightly packed, with the core action front-loaded and the caveat/exception following immediately. Every clause carries information the agent needs; 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 compensates by describing the return value (the zero-padded number). Combined with the concurrency guarantee and the hook-overlap warning, an agent has everything needed to call this correctly, and the 4-param schema is fully self-documented.

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, which sets the baseline at 3. The description's mention of 'a named sequence' versus numbered directories loosely mirrors the sequence parameter's dual meaning, but adds no syntax, format, or default information beyond the schema.

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

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

The description states a precise verb+resource ('Reserve the next number in a sequence') and enumerates concrete sequence kinds (a migration, an ADR, a release), so the agent knows exactly what operation this performs. No sibling tool (declare_intent, remember, recall, etc.) overlaps with this behavior, so there is no ambiguity to disambiguate against.

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 both a when-to-use and an explicit when-not-to-use: the hooks already claim a numbered file's number on creation, so only call this 'for a number you need before writing, or for a named sequence.' That is an unusually clear routing rule for an agent deciding between this and simply creating the file.

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 write (readOnlyHint=false), non-destructive, and closed-world, so the description adds context beyond them: it enumerates the artifacts touched (rules files, hook configs, MCP configs) and notes it also handles a credential. It stops short of stating side effects like whether existing files are overwritten, so not quite 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?

Two sentences, front-loaded with the action and target set, followed by the sibling routing and the return shape. No filler; each clause carries 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 compensates by describing the return values (repo files to write/commit, user files to install, copy-paste snippets). For a single-param setup tool with annotations covering safety, nothing needed 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?

Only one parameter and schema description coverage is 100%, so the schema already fully documents repo_id including the config.json reference. The description adds no parameter-level detail, making the baseline 3 appropriate.

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

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

States a specific verb ("Set up Collide") and resource, and enumerates exactly which agent tools it targets (Codex, Cursor, Windsurf, Cline, GitHub Copilot). It also explicitly distinguishes itself from the sibling 'setup' ("For Claude Code use setup"), so an agent can route between the two without opening either schema.

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

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

Explicitly names the condition that selects this tool (non-Claude-Code agent tools in the repo) and names the alternative ('setup') for the Claude Code case. This is a clear when-to-use / when-to-use-something-else routing.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower and the description adds real context: a 15-minute TTL with heartbeat extension, conflict outcomes (COMMUTE/CONFLICT/UNKNOWN), and hook-triggered side effects on definition and call sites. What it omits is what registering actually does to other agents' intents (blocking, visibility) and what success returns.

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, then the operation grammar, then the hook behavior — a sensible order with minimal filler. The hook sentence is long and clause-stacked, but each clause carries distinct information (which ops, scope, verification, reporting), so little 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 10-parameter mutation tool with no output schema and no annotations beyond the safety hints, the description covers TTL, conflict semantics, retry idempotency, and the optional hook workflow. It stops short of stating the return payload or what the caller should do after a CONFLICT/UNKNOWN result, which is the remaining actionable gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it enumerates all eight typed operations with their field shapes (rename/symbol/new_name, add_param/name/type/default, extract, move, delete, add, modify), whereas the schema only shows one example. It also explains ref (issue/PR link), TTL, and idempotency-driven retry behavior in prose.

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

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

Opens with a specific verb+resource: 'Register an in-flight change', then clarifies the mechanism (typed operations, conflict prediction, TTL). An agent can tell this is about declaring intent, not querying it. It never names or contrasts with siblings like claim, defer_intent, or pending_reconciliations, so it misses the top-tier sibling-differentiation bar.

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?

'PREFER typed operations' and the TTL/heartbeat note imply usage, and the hook paragraph states a concrete condition ('With the native hook installed'). However, there is no explicit when-to-use-vs-alternatives guidance (e.g., when to use claim or defer_intent instead), leaving routing between the 15 sibling tools 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 only cover the safety profile (not read-only, not destructive, open-world). The description goes further by disclosing key behavior: it fires exactly once into the next tool result and briefing, may create a CRM task, and returns the tripwire id and expiry. It stops short of covering permissions, expiry cleanup, or what happens on repeat calls.

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 tightly written sentences with the core mechanic front-loaded and the side effects (one-shot firing, CRM task, return values) packed efficiently into the second. 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?

With no output schema, the description usefully states the return values (id and expiry) and the lifecycle behavior, which is the main thing an agent needs. Minor gaps remain around permissions and durability, but overall it is sufficient to invoke 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 the schema already documents all five parameters. The description reinforces that paths/symbols are the triggers and supplies an example note wording, but adds no syntax, format, or default detail beyond the schema, making the baseline 3 appropriate.

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

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

States a concrete action (create a tripwire that warns the next editor of unfinished work) with the mechanism and effect made explicit. It is distinguishable from declare_intent or remember by describing a persistent, trigger-based warning, though it never names those siblings directly.

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

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

The opening phrase "Leave work unfinished safely" implies the usage scenario, and the example clarifies intent. However, there is no explicit guidance on when to choose this over declare_intent, remember, or claim, nor any exclusions or prerequisites.

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 and destructiveHint=false, and the description redundantly restates 'Read-only'. Its real added value is disclosing what the result contains — edits with author/time/change, completed intents with rationales, reverted attempts, anchored notes, and uncommitted work — which is beyond what annotations cover.

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 purpose, then the content inventory, then the routing rule and safety note in a single efficient paragraph. The colon-separated list is dense but every element earns its place; only the redundant 'Read-only' is wasted given the annotations.

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

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

With no output schema, the description usefully enumerates the kinds of records returned and the ordering, and it covers both path and symbol scoping. Safety and usage context are present, leaving little an agent would need that is absent.

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 are already documented, and the description adds only the 'oldest first' ordering hint. No new syntax or format detail is supplied 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 deliverable — the history behind a path or symbol, oldest first, with who/when/what per edit — which is a concrete verb+resource. It distinguishes itself from git blame and git log by naming them explicitly, so an agent can route without opening the schema.

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

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

Gives an explicit use-before rule ('Use it before git blame or git log') and the reason (uncommitted work and stated reasons are included). It does not name any sibling MCP tool as an alternative or state when not to use it, 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?

Annotations already declare readOnlyHint/destructiveHint false, and the description adds real context beyond them: the hook-based delivery fallback, and a return shape ('summary lines, changed modules with exact signatures, anchored notes and live agents') that matters because there is no output schema. It doesn't cover latency, size limits, or failure modes, but it meaningfully exceeds the annotation baseline.

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

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

The imperative 'Start here for any coding task' is front-loaded and the rest is dense, non-redundant information. It is a long single paragraph, but nearly every clause carries distinct content (contents, hook fallback, path behavior, read-only, return shape) rather than filler.

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

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

With no output schema, the description does the work of describing returns, and it covers trigger, fallback semantics, and the optional blast-radius path behavior. What's missing is minor: guidance on choosing days/depth and any note on cost of a wide or deep query.

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 the causal link that path/symbol 'also' trigger blast-radius computation rather than just filtering, which the schema does not convey. Depth's role is left to the schema, but the path/symbol behavior is genuine added 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?

It states a specific verb (get/generate a briefing) plus the exact resource content: 'the recent history of this repo — who changed what, renames to adapt to, hotspots, abandoned work and who is working right now.' The 'Start here for any coding task' opener and the enumerated contents distinguish it cleanly from siblings like recap, recall, and 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?

It gives a clear trigger ('Start here for any coding task') and an explicit condition for calling it versus relying on ambient context ('Where Collide's hooks are installed the same briefing already arrives in your context; call this when it did not'). It also implies the blast_radius alternative ('Pass path ... to also get the blast radius') but never names that sibling explicitly, so routing is inferential rather than spelled out.

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 and destructiveHint=false, so the trailing 'Read-only' adds nothing; credit comes from the disclosed default behavior when `symbol` is omitted (whole-module scan) and the explicit statement that it works without opening the file. Permission/rate-limit behavior is not covered, keeping this below a 5.

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

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

Two dense sentences with no filler, and the payload description is front-loaded before the routing clause. The semicolon-heavy first sentence is information-rich but slightly hard to parse, which keeps it from 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?

With no output schema, the description carries the burden of describing return content, and it does so (signature, params, calls, span, hash, notes, check status). Missing are error behavior for an unknown symbol/path and what the 'check' actually represents.

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

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

Schema description coverage is 100%, and the schema itself already documents path, symbol (including 'omit for the whole module'), and repo_id. The description restates the omit-symbol default but adds no format, syntax, or constraint details beyond the schema, 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?

States a concrete verb+resource (facts about a symbol) and enumerates exactly what comes back: signature, parameters, calls, span, hash, notes, check status. It also distinguishes itself from siblings by naming blast_radius as the tool for a different question.

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 routes the agent elsewhere for the adjacent need ('use blast_radius for who depends on it'). The when-to-use condition and the named alternative are both present, 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 already declare non-readOnly, idempotent, non-destructive. The description goes beyond them by disclosing the side effect (messages stop arriving), the cost of omission (unacknowledged messages repeat on every response), and the return value (messages still pending). Adds real 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?

Three tight clauses, front-loading the purpose and effect before the how-to. Every sentence earns its place, though the trailing return-value sentence is slightly separable.

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

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

For a mutating tool with no output schema, the description covers the trigger, the effect, the repeat penalty, and the return value. Complete enough to call correctly; only the repo_id source is left entirely to the schema.

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 ids and repo_id are already documented. The description's 'ids from messages_pending' largely restates the schema's own id description and adds no format/syntax detail. Baseline 3 is appropriate.

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

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

States a specific verb (Mark...as handled) and resource (messages from teammates' agents), and names the concrete effect (so they stop arriving). An agent can tell this apart from siblings like send_agent_message or recall without opening any schema.

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

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

Gives clear triggering condition: 'pass the ids from messages_pending once you have acted on them.' The repeat-on-every-response note reinforces when it must be called. No explicit when-not or named alternative, but the context is unambiguous.

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 readOnlyHint=false and destructiveHint=false, so the mutation profile is partly covered, but the description adds meaningful behavior beyond them: the keep-both-sides merge rule, the explicit prohibition on deleting, and the two-phase claim-then-resolve flow. It does not describe what state persists or error conditions.

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 trigger condition, then the action, merge rule, and second-call pattern, ending with return values. Dense but every clause carries instruction; no filler sentences.

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, and the description compensates by stating what is returned (claimed reconciliations and remaining open count). The two-mode contract and merge constraint are covered; only edge cases and failure behavior are absent.

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 operational meaning by showing resolve=[id] is only supplied on the second call after a verified merge, which the schema alone does not convey. repo_id semantics are left to its schema 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 names a specific resource (open reconciliations/collisions) and verb (claim, then resolve), and reveals that the tool has two modes rather than just listing pending items as its name suggests. It is clear what the tool does, though it doesn't explicitly contrast against sibling tools like claim or declare_intent.

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

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

It gives an explicit trigger (when a response reports reconciliations_pending), prescribes the merge policy (keep both sides, never delete either), and specifies the follow-up call (resolve=[id] after tests pass). Both invocation modes and their ordering are spelled out.

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 and destructiveHint=false, so the safety profile is covered; the description reinforces 'Read-only' and adds genuinely new behavior: newest-first ordering, empty-query fallback to most recent, and that results carry anchor, confidence and staleness flags. It does not cover pagination beyond the limit parameter, so it is strong rather than exhaustive.

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

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

The core action and its scoping/ordering rules are front-loaded in the first clause, followed by a short usage directive and the return-shape note. Every sentence earns its place with no filler.

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

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

There is no output schema, so the description takes on the burden of describing returns and does so (anchor, confidence, staleness). Combined with the usage cue and the empty-query fallback, 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 the baseline is 3; the description adds value beyond the schema by stating the relevance/ordering model (newest first) and the empty-query behavior, and by clarifying that tags are conjunctive in prose. The repo_id and limit semantics remain schema-only, but that is already well documented there.

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

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

States a specific verb (search) and resource (the team's saved notes), plus filtering axes (text and tags) and ordering (newest first). It explicitly ties itself to the sibling tool that creates these notes ('made with remember'), so an agent can separate recall from remember 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 a concrete use condition: 'Use it before re-deciding something the team may already have settled,' and implicitly frames remember as the write counterpart. It stops short of naming explicit exclusions or other retrieval siblings (e.g. recap, get_briefing), so usage routing is clear but not exhaustive.

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

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

Annotations already establish readOnly, non-destructive and closed-world, and the description's 'Read-only' merely restates that. The value-add is the return shape — one entry per session plus a dashboard link — which is real behavioral context given there is no output schema.

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

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

Three tight sentences front-loaded with the payload contents, then the usage question, then the return shape. Nothing is padded, and the only slight redundancy is 'Read-only' against the annotation.

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 sketches the return (one entry per session, dashboard link). It omits any mention of result volume or cost-estimation caveats, but for a two-parameter read tool it is close to sufficient.

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

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

Schema description coverage is 100%, with days and repo_id both documented in the schema itself, so the baseline is 3. The description adds no extra semantics for either parameter (e.g. the 90-day ceiling or repo_id format), so it neither compensates nor detracts.

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 names a specific resource set — per-session agent activity with edits, lines, tokens, model, cost, rationales and top paths — so the agent knows exactly what comes back. It does not, however, contrast itself with close siblings like recall or get_briefing, which is the missing element for a 5.

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

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

It gives clear triggering questions: 'what happened' or 'what did this cost'. That is a usable when-to-use signal, but there are no exclusions or named alternatives, 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?

Annotations declare a non-destructive write, and the description adds real behavioral context: anchored notes surface to whoever touches that code, get marked stale on rewrite, and supersedes retires the old note. That goes well beyond the safety hints, though nothing is said about rate limits or write 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, front-loaded with the core purpose and the key distinction from code state. Every clause carries information, though the anchoring detail is packed tightly enough to require a second read.

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

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

For a 6-parameter write tool with no output schema, the description covers purpose, anchoring semantics, batching implication, and return value ('returns their ids'). Minor gaps remain around tag conventions and batch limits on facts.

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 meaning beyond the schema: it explains the operational consequence of anchor (reaching code touchers, staleness) and the retirement behavior of supersedes. The anchor form examples reinforce the schema's field syntax.

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') and sharply scopes the content ('a decision, constraint or gotcha, not code state'). The explicit exclusion of code state distinguishes it from retrieval siblings like recall and recap.

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

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

Clear guidance on what to store and when to anchor ('facts about specific code'), with concrete anchor syntax examples. It does not explicitly name recall as the counterpart read tool, so the routing is implied rather than stated.

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 mark this as a non-destructive write, but the description adds delivery mechanics (arrives with their next tool result), recipient-side context (they see whether the code changed and whether tests passed since), and return values (message id and recipient). This is meaningful behavior far beyond the annotation set.

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 two routing modes and keeps every clause informative, though the anchor sentence is dense enough that it takes a second read to parse the recipient-selection rule.

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 covers return values, delivery timing, and both routing paths, so 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, but the description adds real semantics beyond the schema: the anchor resolution rule (open intent or last-day edits, including callers) is not captured in the schema's terser 'path.py::symbol, path.py, or dir/' text.

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

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

States a specific verb (send) and resource (message to teammates' agents) and immediately disambiguates the two routing modes (to vs anchor). An agent can distinguish this from siblings like connect_agents or inbox_ack without opening the schema.

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

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

Explicitly defines the selection conditions: use `to` with one account email, or use `anchor` alone (no `to`) to reach whoever has an open intent on or recently edited the code or its callers. This is genuine when/how-to-use guidance, not implied.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description goes well beyond that, disclosing the side effects (installs the pinned hook binary, writes config, merges settings, installs credentials) and the follow-up obligation to commit what it stages. That is exactly the mutation context an agent needs.

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

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

Three sentences, front-loaded with the core purpose and the once-per-repo constraint before the procedural detail. Dense but every sentence carries information; the parenthetical enumerating the command's effects is slightly packed but earned.

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 correctly covers what is returned ('the command or the files, and what they install'). Combined with annotations covering the safety profile, an agent has enough to call it correctly; only the already-configured case is unaddressed.

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

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

Schema description coverage is 100%, with repo_id and the enforce/advisory/files mode values already documented in the schema. The description reinforces the files path but adds no new syntax, format, or default semantics beyond what the schema provides, 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 in a repo, and adds the strong qualifier 'once per repo'. It also previews the two output shapes (a command vs files), so an agent knows what the call produces. It does not explicitly contrast with siblings, but none of them (blast_radius, claim, recall, etc.) overlap with setup.

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

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

Gives a clear invocation condition ('once per repo') and branching guidance: run install.command exactly as given at the repo root if present, otherwise write the returned files and commit. It does not spell out when setup should be skipped (e.g. already configured), so a small gap remains.

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