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

There are no annotations, so the description must carry the behavioral burden. It does so well by disclosing routing through existing granular tools, preserving entitlement/readiness/validation/mutation-safety checks, automatic compression, clarification behaviour for ambiguous targets, and the incomplete-response protocol via completion_state, agent_instruction, and next_tool_calls. It does not explicitly mention side-effect potential or confirmation semantics, but the information is generally thorough.

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 clearly structured into an overview, replacement statement, and short/long usage guidance. It is a bit longer than necessary, with some repetition around the same 'Use first' and 'instead of alternatives' ideas, but every section earns its place given the tool's complexity and broad role.

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

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

Given that the tool has 16 parameters, nested objects, no output schema, and no annotations, the description does a good job of covering the common and even advanced flow: scoping, exact identifier, mutation payload, feedback/identity, confirmation_token, compression, and next_tool_calls. It does not fully explain return shape, confirmation UI authority explicit cases, or when the agent should bypass the router, so I deduct a little for those gaps.

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 description coverage is 69%, and the description adds meaning beyond the schema in the right places: it explains query, top-level repo_id/path vs. global aliases, where mutation payload must live, how deletion-safety targets should be supplied, and how to use returned route ids. However, certain parameters such as depth, limit, format, and preview_digest remain unexplained.

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 identifies the tool as the default Synapse entry point that routes natural-language objectives across a defined set of tasks (questions, deletion-safety, edits, reviews, debugging, test discovery, repo administration, capability discovery). It distinguishes the tool from the granular sibling tools by framing it as the intelligent router preferred over manual tool selection.

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, actionable guidance: use this first, prefer top-level repo_id and path, supply concrete identifiers in inputs, and for deleting queries provide chunk_id or a qualified symbol rather than vague prose. It stops short of presenting a clear when-not-to-use case or alternatives for bypassing the router, but the routing context is strong.

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

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

With no annotations, the description carries full burden and delivers spef: it says the output is 'live', includes 'mutation characteristics', 'safety class', 'tool relationships', and mentions compression and token behavior. It could explicitly state no side-effects, but the content is substantially transparent for a meta/manifest tool.

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 organized into sections and is mostly useful, but the 'Usage (short)' line duplicates the first sentence almost verbatim ('Return a structured manifest...' / 'Returns a structured manifest...'). This redundancy costs the description a higher score.

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?

Without an output schema, the description compensates by enumerating what the manifest includes: schemas, mutation characteristics, safety classification, relationships, ready routing, and quick_start. It gives enough for an agent to understand the return surface, though it could still describe the manifest's literal top-level format.

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 explains all 7 optional parameters. The description adds no new per-parameter detail beyond referencing compression and discovery, which is consistent with the baseline value for when schema does the heavy lifting.

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 and resource: 'Return a structured manifest describing SynapseMCP's live tool surface,' and enumerates concrete contents (schemas, mutation characters, static safety classification, tool relationships). This clearly distinguishs it from the 11 siblings, none of which present a meta-manifest of the tool surface.

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 usage context: 'a replaces: reading MCP tool schemas manually h trial-and-error tool discovery' and says 'Use this tool instead of these alternatives'. It doesn't cover when-not-to-use or name sibling alternates, but the context is unmistakeable.

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?

There are no annotations, so the description must carry the behavioral burden. It discloses what each action produces—modified symbols, must-read files, tests to run, contract signals, blind spots, blast radius, downstream callers, and change risk—and mentions automatic token compression. It does not explicitly state read-only behavior, but the analysis/review framing strongly implies it.

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 well-structured with a punchy lead sentence, action bullets, and explicit replacement topic. However, the Usage short and Usage long sections partially repeat the same guidance, and the REPLACES paragraph is slightly redundant with the opening line.

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 no output schema and no annotations, the description does a good job of covering all three action modes and their outcome categories, plus when to invoke the tool. It is slightly weakened by not explaining exactly how the diff/commit-range/file-list input is provided, since no input parameter exposes 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%, but the description adds substantial semantic value beyond the bare 'action' property by explaining what each enum value does. It also links compress_payload to the token-compression behavior and describes the high-level result categories agents can expect, which helps parameter selection.

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 begins with a specific verb and resource: 'analyses and reviews proposed changes' via diffs, commit ranges, chunk lists, or file lists. It further clarifies the three concrete action modes and explicitly distinguishes itself from alternatives like git diff, manual diff review, and grep_search.

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 'REPLACES: git diff, manual diff review, grep_search' and tells the agent to use this tool 'instead of these alternatives'. It also gives situation-specific guidance: use after making changes to verify safety, or before merging to assess risk, plus when to inspect commit/branch diffs or before refactoring.

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

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

With no annotations, the description carries the full behavioral burden and responds well for 'dead_code': it labels the check read-only, highlights that no source is deleted, lists confidence/risk/caveats, and disposes of unsupported clause-level analysis. Other actions get lighter treatment and no return-shape details, so the transparency is good but not complete.

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 organized as a summary, per-action bullets, then a short usage block; it is front-loaded and uses lists well for a multi-action tool. The 'Usage' wording does partially repeat the action list, but the repetition is moderate for the complexity being described.

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-output-schema tool with seven action modes, the dead_code sub-case is very complete. Other actions are described enough to be understood but 'refactor_opportunities' remains under-specified, and the schema does not actually expose the personnel IDs/symbols/chunk identifiers the description asks for, leaving an invocation 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?

All three actual parameters already have schema descriptions, so the description is not required to carry the parameter documentation burden. It does add meaning by explaining what each action enum value accomplishes. However, the dead_code instructions tell the agent to pass repo_id/symbol/chunk_id arguments that are absent from the provided input-schema, which is misleading for actual call construction.

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 names concrete resources — codebase structures, API boundaries, contracts, dependencies, and deletion safety — and the action bullets map directly to the schema enum, so the tool's purpose is clear and distinguishable from search/modify siblings. It loses a point because 'refactor_opportunities' is part of the enum but only mentioned in passing rather than given an explicit action bullet.

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 guidance for the most complex case: use 'dead_code' as the backend for ask_synapse questions like 'can I delete X?', and prefers the chunk_id over a raw symbol. It also tells the agent to ask for the concrete symbol instead of guessing and to use 'detect' before choosing search modes. It stops short of naming when-not scenarios or explicit sibling exclusions.

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

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

With no annotations, the description carries the full behavior burden. It does disclose that the tool does not run code and that it reduces token usage via automatic compression. However, it does not mention potential side effects of the save_to_file parameter, any indexing/prerequisite requirements, or whether resolution can fail for unknown stacks, so the transparency is incomplete.

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 purpose and organized into scannable sections: actions, REPLACES, short usage, and long usage. There is some redundancy between the short and long usage sections, but each section generally 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 3-parameter tool with no output schema and no annotations, the description provides enough context to understand what the tool does, when to choose each action, and what results conceptually look like. It does not fully describe output structure or prerequisite conditions, but the prose covers most of what an agent needs.

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 covers all three parameters with high description coverage, giving a baseline of 3. The tool description adds meaningful semantics to the action enum by explaining exactly what 'trace_behaviour' and 'resolve_stack' do, while the schema still handles the function signature and save_to_file details.

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 ('Traces code paths or resolves error stack traces...') and names two concrete high-level actions, each with clear inputs and outcomes. It clearly distinguishes this tool from the sibling tools like synapse_search_codebase or synapse_inspect_files.

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 what this tool replaces: manual stack trace reading, grep_search for error origins, and sequential file reads, and tells the agent to use this instead. It also gives action-specific guidance: use trace_behaviour to understand function flow without running it, and use resolve_stack to map crash frames to chunks and root cause.

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

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

With no annotations, the description carries full disclosure burden and does it well: it explains transitive behavior, depth 1–3, automatic compression, and warns graph results can be large. It doesn't explicitly state 'read-only,' but the action names and context imply no 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 longer than typical but well-structured with bullets, preprocessing examples, and front-loaded action list. There is some redundancy, such as telling the message that 'no separate lookup needed' and 'Replaces...manual caller guessing' twice, but the overall shape is usable.

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 behavior context is complete for a read-only, no-annotations, no-output-schema tool. It covers what is returned, how to specify targets, depth options, token-saving, compression, and which alternatives to replace. The agent has enough information to select and invoke the tool in most realistic graph-query scenarios.

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 already documents all three declared properties, so baseline is 3. The description adds real semantics: action values, how chunk_id/repo+symbol/file_path are accepted, depth behavior, and actual invocation examples. However, it references target fields like repo_id, symbol, and depth that are missing from the input schema, which oils any agent invocation and prevents a pointerfect score.

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 the core purpose clearly: 'Explores structural relationships within the codebase graph' and then catalogs the four concrete actions. It distinguishes itself from siblings by naming grep_search, find_references, and caller guessing as alternatives it replaces.

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 explicit guidance on when to use the tool and what alternatives it replaces, plus three ways to specify a target and one-call examples. It also advises using depth 2+ for multi-hop results instead of chaining depth-1 calls.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does well: it explains the at-most-5 high-confidence match cap without repo_id, mentions meta.unscoped_retrieval, details what each action gathers or produces, and discloses token compression behavior. A small gap is that it never explicitly states that this is a read-only operation and never mutates code, though calling it 'retrieves' strongly implies it.

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 well-structured and front-loaded with high-level purpose and actions, but it repeats key points: 'Pass the exact repo_id...' appears multiple times, and 'action edit' is emphasized twice. The 'Usage (short)' vs 'Usage (long)' sections also add redundancy. Overall, it is longer than necessary, but the information is organized and relevant.

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 complexity of this tool (19 parameters, no output schema, no annotations), the description is largely complete: it covers all four actions, tells the agent how to obtain a repo_id, explains behavior without repo_id, and describes what the edit action should gather. It does not fully describe the overall return value structure, but the action-level descriptions and the schema help bridge most of that 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?

The input schema has full 100% description coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains why action 'edit' is the essential pre-edit step, clarifies the impact of omitted repo_id, and breaks down what each high-level action does (e.g., find's multi-mode search, explain's layered explanation, and onboard's reading order). This is extra practical guidance, not just schema repetition.

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 identifies the tool's purpose: retrieving codebase context for understanding, editing, explaining, and onboarding. It names specific actions ('find', 'edit', 'explain', 'onboard') and directly distinguishes itself from alternatives like 'multi-file grep_search chains, sequential view_file reads' and manual code comprehension.

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 on when to use this tool, when not to, and how to handle edge cases. It says to pass the exact repo_id, to call synapse_manage_repos with action 'list' when repo_id is unknown, and that action 'edit' is required before modifying code. It also includes 'Instead of these alternatives' guidance, which helps an agent route to the right tool.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses status caching with idle vs. active timing, trigger's re-index side effect, cheap vs. slower options, wait-for-idle behavior, direct SQLite lookup for repo-scoped status, and output compression for lower token usage.

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 structure is front-loaded and skimmable: action bullets, REPLACES, a short usage note, then detailed status output. It is slightly redundant because the later status-return block partially repeats and rephrases the earlier 'status' bullet, but the overall layout remains usable and organized.

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 compensates by enumerating status fields, unresolved-edge counts, top candidates, caching behavior, and readiness guidance. For a 9-parameter tool with three distinct actions and no annotations, the description is comprehensive enough to drive the apparently action selection and parameter choice without external documentation.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining that repo_id selects a direct SQLite lookup, include_profile trades speed for detail, and trigger accepts a file/directory path. This helps the agent map intentions to parameters more accurately.

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 'Controls and inspects the indexing pipeline and server health,' which is a specific verb and resource, then elaborates with three concrete actions: health, status, and trigger. It clearly differentiates this tool from sibling content tools like synapse_search_codebase and synapse_modify_files, whose domains are code search and file editing rather than indexing pipeline control.

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 usage sequencing ('health' first), repo_id scoping guidance, and a REPLACES line directing use instead of manual health probing, process monitoring, and ad-hoc tool listing. It lacks explicit when-not-to-use guidance against related sibling tools such as synapse_manage_repos, but the core usage context is still clear.

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

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

No annotations are provided, so the description carries the full transparency burden; it meets most of it by explaining that read_files reads from disk, read_chunk reads from an in-memory store with no disk access, and count_lines counts across workspace files. It also discloses default compression behavior, the compress_payload opt-out, and the outline format compression effect. It stops short of describing exact return shape or failure behavior, which would make it fully transparent.

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 well-structured with a front-loaded purpose, bulleted actions, a REPLACES note, and clear usage sections. There is a small redundancy between 'Usage (short)' and 'Usage (long)', which costs some conciseness, but the overall structure is highly scannable for an agent.

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 tool with three inner actions and eleven parameters, the description is fairly complete: it describes what each high-level action does, where the data comes from, the outline option for large scans, and the default compression behavior. There is no output schema, but the description provides enough return-oriented context for each action. The main gap is that it does not specify which parameters apply to which action, leaving the agent to infer those relationships from 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?

The input schema already covers 100% of the parameters, so the baseline is 3. The description adds useful grouping of actions and states that read_files returns line numbers, byte sizes, and metadata, plus that outline compresses function bodies. However, for most parameters like repo_id, chunk_id, max_read_bytes, and wait_for_ready_ms, the description does not add meaningful meaning beyond the schema; thus it earns the baseline but not substantially more.

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 ('Inspects files in the workspace') and then enumerates three concrete high-level actions: read_files, read_chunk, and count_lines. It further disambiguates from legacy inspection tools by saying 'REPLACES: view_file, read_file, cat, wc, list_dir', so an agent clearly understands what this tool is for.

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 on when to use this tool instead of older alternatives, noting it 'provides better results with 30-60% fewer tokens via automatic compression'. It also provides task-level advice: use 'outline' format when scanning many files, and pass 'compress_payload: false' to opt out for debugging, which is actionable usage direction.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It explains persistence, that learn signals are immediately queryable but provisional until promoted by repeated evidence, that save_summary permanently annotates chunks, and that suggest uses access history and traffic weight. This goes well beyond schema details, though it could be clearer about mutation side-effects and exact behaviors for save_summary beyond persistence.

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 substantially repetitive. The action list, 'Usage (short)', 'Usage (long)', and the later 'Call learn'/'Call query' paragraphs all restate the same action set with slight wording differences. It is conceptually organized, but several sentences do not earn their place because they reproduce information already covered.

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 four-action tool with no output schema and no annotations, the description covers most of what an agent needs to select, call, and understand each action. It defines behavior, input patterns, and outcome intent. It could be more complete by describing return payloads per action and explicitly naming what distinguishes this tool from the codebase search/insight siblings.

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 supports action semantics by explaining what each enum value does, but it does not deepen the semantics of max_tokens or compress_payload beyond what the schema already describes. This is acceptable given full schema coverage.

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's role as a persistence/knowledge cache and enumerates four concrete actions with explicit result types. It differentiates itself from raw searching by positioning itself as a cache for established patterns, though it does not explicitly distinguish itself from sibling tools such as synapse_search_codebase.

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 provides solid usage context: call learn after useful search results, call save_summary for permanent annotations, and call query with natural language/filenames/symbols/chunk IDs. It says this tool replaces repeated searches, manual notetaking, and rediscovery, but it does not name the actual sibling alternatives, leaving the when-not-to-use boundary slightly implicit.

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

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

With no annotations, the description carries all behavior responsibility. It states that unregister permanently removes graph data, archive stops indexing but keeps graph searchable, restore restarts indexing, and keep dismisses advisory only for the session. The behavior of auto-detecting worktrees and auto-archiving clean merged worktrees is also disclosed.

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 uses a short introductory sentence, a numbered action list, a dedicated advisory block, and lifecycle rules. It is longer than typical descriptions, but every sentence is procedural or save-making. The critical warning about absolute paths appears immediately before telling the user to avoid '.' relative paths, so it is both front-loaded and actionable.

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?

This is a 8-parameter with no output schema, so the description must provide enough operational context. It does: it explains the return meaning of list, the unique dirty-worktree situation and recomended actions, the effect of archive/restore/keep/unregister, and the correct order of actions. The agent is fully equipped to sequence 'list' → respond to suggested_actions → invoke the proper action.

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?

Although schema coverage is 100%, the description adds meaning clearly beyond the schema: root must be an absolute path and never '.', repo_id is required for most actions and optional for quick single-repo detail, and 'list' rows actually return suggested_actions that trump the state-aware next step. This is exactly the kind of parameter insight an agent needs.

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 concrete responsibility — 'Manages repository registrations' — and enumerates all seven actions it supports. This makes the tool's boundary clear and distinguishes it from sibling tools such as search, file modification, or indexer control.

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 selection guidance: lifecycle rules say when to use archive vs restore vs unregister vs keep, and a 'REPLACES' block says to use this instead of ls/find and manual worktree management. It also instructs to call 'list' first when unsure of repo_id.

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

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

With no annotations available, the description carries full disclosure burden and does so thoroughly. It reveals atomic lint validation, dry-run semantic simulation, blast radius mapping, rollback on lint failure, permanent chunk deletion, re-indexing, and the fact that dry_run: true never touches disk.

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 long, but the tool is complex and 17 parameters; bullets and separate Usage sections keep it scanable. There is some repeated safe dry-run guidance across the intro and long usage, preventing a perfect score.

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-annotation tool with no output schema, this description is unusually complete: safe workflow, action semantics, lint/rollback behavior, compression, and the required preceding call to get_conext are all present. An agent can safely invoke first dry-run and decide whether to apply.

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 already strong; the description adds the phase-driven semantics of dry_run/pre_check/lint and groups filters for find_and_replace. It does not describe every parameter, but it does meaningfully bind the most safety-critical and action-specific properties.

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 clear resource and scope ('files in the workspace') and then enumerates the three concrete actions: write_safely, find_and_replace, and delete_chunk. It also explicitly names the alternatives it replaces, so an agent can distinguish this tool from legacy or sibling editing tools 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?

It gives a concrete safe workflow: call write_safely with dry_run, pre_check, lint true, review preview, then call apply with dry_run false. It also names a necessary preceding tool (synapse_get_context) and states when this tool should replace common alternative tools.

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

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

No annotations provided, so description carries full burden. Discloses: compression behavior (on by default, opt-out for debugging), unscoped retrieval policy (5-result cap, score thresholds), embedding dependency (semantic requires embeddings, avoid when embeddings_partial), and freshness behavior (symbol/regex work immediately after quick_pass). This is remarkably thorough for a non-annotated tool.

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?

Well-structured with short usage + long usage sections, action list, and explicit alternatives. Front-loaded key information (exact repo_id, action modes). Some redundancy between short and long usage sections (both repeat repo_id guidance) is a minor cost, but acceptable for a complex tool.

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 16-parameter complex tool with no output schema, the description covers action selection, result caps, score thresholds, repo scoping, fallback tip (call synapse_manage_repos list), and freshness behavior. Nothing critical is left out 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 already covers 100% of parameters with rich descriptions (per-action semantics, defaults, purpose). Description adds value by explaining cross-parameter dynamics (repo_id's effect on score thresholds, compress_payload's debugging use case) that the schema lacks. Slightly less than 5 because most parameter meaning is already in the schema rather than in the 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?

States a specific verb+resource: searches codebase with 3 distinct modes (semantic, symbol, regex). Explicitly distinguishes from grep_search/find/rg/list_dir — names alternative tools it replaces. The three action modes are clearly differentiated by search type and use case.

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 guidance per action mode ('best for conceptual...', 'best when looking for...', 'best for exact...'). Explicitly names alternatives (grep_search, find, rg, list_dir) and states when to replace them. Also gives concrete behavioral guidance about repo_id and fallback actions.

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

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

With no annotations present, the description carries the full behavioral burden and mostly delivers: it discloses the 5-match cap, the direct-confidence limitation, nested repository exclusion, and default compression. It is slightly less transparent about setup_trunk's side effects on the existing lint configuration, but 'automatically configures Trunk linting and enables recommended linters' does convey that it changes repo state.

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 content is well-organized into actionable bullets and usage sections, and most sentences carry useful detail. However, there is noticeable redundancy: the 'Usage (short)' restates the action list, and the 5-match cap on unscoped find_tests is described twice. Trimming these would make it more concise.

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?

This is a multi-action tool with no annotations and no output schema, and the description is not enough on its own. It references repo_id, symbols, queries, and targeted path filters, but the schema only exposes action, max_tokens, and compress_payload; an agent cannot reliably determine how to provide the required inputs for find_tests or recommend_test_targets. Important return/result structure details are also 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 the baseline is 3 and the description is not required to re-explain action, max_tokens, or compress_payload. The added prose references repo_id and symbol/query concepts, but those are not present in the input schema, so it makes parameter semantics somewhat ambiguous for an agent trying to construct valid calls.

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 begins with a clear scope of code quality, testing, and lint control, then enumerates four concrete actions with specific verbs: coverage reports, find_tests discovers, setup_trunk configures, and recommend_test_targets recommends. It also differentiates itself from generic test-file discovery via grep_search, making it distinct within its sibling set.

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 use this tool instead of grep_search, manual test file patterns, and manual test-to-code mapping, and gives a token-saving rationale. It also adds usage detail about scoped versus unscoped find_tests behavior. It does not fully articulate when NOT to use this tool versus the other synapse_* siblings, so it loses the top score.

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