MCP server for entity-level semantic merge: read merge findings and cross-file binding risk, and coordinate live multi-agent edits via a shared CRDT. 22 tools.
Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
weave-mcp presents a sophisticated entity-level merge coordination server with 18 well-namespaced tools. Strengths: all tools follow verb_noun naming convention with 'weave_' prefix, descriptions are present and contextually detailed (avg 150-200 chars), input schemas are fully visible and properly typed. Critical weaknesses: (1) NO output schemas documented anywhere in the codebase, tools return results but callers cannot predict structure; (2) descriptions lack explicit 'when to use' guidance and error recovery hints that LLMs need; (3) parameter descriptions sometimes generic ('Path to the file') when they could guide format/constraints; (4) no tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear read/write distinction provided in risk metadata. The 18-tool surface is well-factored into single responsibilities (claim, release, update, list, analyze separately) and composition works (e.g., claim → update → release chain via entity_id), but the lack of output documentation and LLM-centric error guidance prevents this from reaching 70+.
Tools (18)
weave_agent_heartbeatwritesource verified78/100
Send a heartbeat with the current work-in-progress entity list
weave_agent_registerwritesource verified81/100
Register an agent with the CRDT (for multi-agent coordination)
weave_claim_entitywritesource verified84/100
Claim an entity for editing by an agent (CRDT-based coordination)
weave_diffread onlysource verified78/100
Show entity-level diff between two refs (branches, tags, commits)
weave_entity_depsread only50/100
Analyze cross-file binding risk: which entities depend on this one
No output schemas documented. Tools return results but callers cannot predict field structure, types, or required vs optional fields. Forces LLMs to guess response shape and risks malformed downstream tool chaining.
Document output schemas for all 18 tools. For each tool, add a 'Returns' section to the description or a separate outputs.json file specifying field names, types (string, number, boolean, object, array), required vs optional, and semantic meaning. Example for weave_status: 'Returns: {"file_path": string, "entities": [{"name": string, "type": string, "claimed_by": string | null, "timestamp": ISO8601}], "total_entities": number}'. This is CRITICAL for LLM chaining.
Add tool annotations to schema. For each tool, add 'annotations' field per MCP spec: READ_ONLY tools get {"type": "resource", "readOnlyHint": true}; WRITE tools get {"type": "action", "destructiveHint": true}; idempotent tools get {"type": "action", "idempotentHint": true}. Example: weave_extract_entities should have readOnlyHint: true.
Enhance parameter descriptions with format/constraint guidance. Rewrite generic descriptions to include validation rules, examples, and dependency hints. Example: 'file_path (string): Relative path to source file within repo (e.g., 'src/main.rs'). Must exist and be parseable by weave-core. If unsure, call weave_list_files first.' Apply this to all entity identifier parameters (entity_name, entity_type, parent_name, ordinal).
Add error recovery guidance to tool descriptions. For each write tool, append an error section. Example for weave_claim_entity: 'Errors: if entity_name not found, returns 404 with available entity names in same file, call weave_extract_entities(file_path) to list valid entities. If already claimed by another agent, returns 409 (conflict), call weave_who_is_editing(file_path, entity_name) to identify the holder and coordinate via agent_id or release the conflicting claim first.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 16 points across a rubric change (v1 → v2)
69/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
C
69
<=2025-11-25
v2
2026-03-09
D
53
-
v1
read onlysource verified77/100
Analyze what will break if this entity is deleted or changed
weave_list_filesread only50/100
List all files in the repository with supported parsers
weave_merge_auditread onlysource verified77/100
Audit a merge: entity resolution decisions and any conflicts
weave_merge_summaryread onlysource verified76/100
Parse weave conflict markers and show a structured summary
Parameter descriptions lack explicit constraints and format guidance. Examples: 'Path to the file (relative to repo root)' should specify path syntax/validation; 'Branch the agent is working on' lacks guidance on valid branch names or resolution strategy; 'List of entity IDs' lacks clarification on ID format. Rubric baseline: 100% of A+ tool params have actionable descriptions.
No error recovery guidance. Tool descriptions omit 'what to do if this fails' hints. Example: weave_claim_entity ('Claim an entity for editing') does not state what error conditions exist (entity not found? already claimed? permission denied?) or how to recover. Agents cannot self-correct without explicit error guidance.
No dry-run or confirmation pattern for destructive writes. weave_update_entity_content and weave_release_entity are write operations with potential side effects (concurrent-edit backstop, claim release) but lack confirmation/preview steps. Agents could execute irreversible edits without review.
Descriptions lack 'when to use' context. Examples: weave_who_is_editing vs weave_potential_conflicts both detect conflicts but serve different purposes, descriptions don't explain the distinction or when to prefer one over the other. LLMs waste reasoning choosing between similar-sounding tools.
Implement pagination for discovery tools. Add limit (default 20, max 100) and offset (default 0) parameters to weave_extract_entities, weave_list_files, weave_entity_deps, weave_impact_analysis. Return total_count in response so agents can iterate. Example: weave_extract_entities(file_path, limit=20, offset=0) → {entities: [...], total_count: 145, next_offset: 20}.
Clarify tool disambiguation in descriptions. For weave_who_is_editing vs weave_potential_conflicts, add: 'Use weave_who_is_editing to query a specific entity; use weave_potential_conflicts to find ALL conflicts across all files/agents.' For merge preview/validate/audit, specify: 'preview = optimistic diff; validate = semantic conflict check; audit = detailed resolution trace.'
Add dry-run or preview capability to write tools. For weave_update_entity_content, support a 'preview_only: boolean' parameter (default false) that returns the merged result without committing. For weave_claim_entity, add weave_preview_claim(...) tool that returns 'would claim OK' or 'CONFLICT: already held by agent-X' without state mutation.
Document entity_id resolution semantics. clarify that entity_id from weave_claim_entity (1) survives renames and (2) bypasses name-based lookup in weave_release_entity and weave_update_entity_content. Add examples: 'Claim returns entity_id='e123'; if entity renamed mid-session, Release still uses e123 instead of new name.'
Add per-tool dependencies and examples in descriptions. Example for weave_update_entity_content: 'Typical workflow: (1) weave_claim_entity(agent_id, file_path, entity_name) → entity_id; (2) weave_get_entity_content(...) to read current code; (3) weave_update_entity_content(..., entity_id, new_content) to commit edit; (4) weave_release_entity(..., entity_id) to unlock.' This chains tools and prevents agent confusion.
Return IDs and references needed for chaining. Ensure weave_extract_entities returns entity_id (if applicable), weave_who_is_editing returns agent_id and claim timestamp, weave_list_files returns file_path in exact format for downstream calls. Validate via the pattern: tool A output contains all params tool B needs.