Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
ConPort has 17 tools with mostly complete schemas and descriptions. Naming is generally clear with action verbs (get_, update_, log_, search_, etc.), though some tools have overlapping concerns. Descriptions are adequate (typically 50-150 chars) but lack depth on WHEN to use each tool and HOW they interact. Parameter descriptions are present and mostly clear, with appropriate use of enums (e.g., status, direction). However, output schemas are NOT documented in the provided code, we can infer them from descriptions but cannot verify the actual response structure. Error handling guidance is minimal. The tools are well-decomposed and handle the context/decision/progress/pattern domains coherently, but lack the LLM-optimized guidance that would push this into A territory.
Tools (17)
detect_workspaceread only50/100
Auto-detects the current workspace root based on project indicators.
get_active_contextread onlysource verified82/100
Retrieves the current working focus, recent changes, and open issues.
get_decisionsread onlysource verified80/100
Retrieves a list of logged decisions, optionally filtered by tags.
get_linked_itemsread onlysource verified80/100
Retrieves items linked to a specific context item.
get_product_contextread onlysource verified82/100
Retrieves the overall project goals, features, and architecture.
get_progressread onlysource verified80/100
Retrieves progress entries for a workspace, optionally filtered by status.
get_system_patternsread onlysource verified80/100
Retrieves system patterns, optionally filtered by tags.
Output schemas not documented. While input parameters are clearly defined with types and descriptions, the actual response structures (what fields are returned, their types, and what IDs/references are included for chaining) are not visible in the provided code. LLMs cannot plan downstream tool calls without knowing what a tool returns.
Minimal error handling guidance. Tool descriptions do not explain what to do if a workspace is not found, a semantic search returns no results, or a link operation fails. Error responses should tell the LLM what to do next (e.g., 'If workspace not found, try detect_workspace() first').
Document output schemas for all tools. Create a schema definition (in tool annotations or accompanying docs) that shows: (1) what fields each tool returns, (2) their types (string, object, array, number, etc.), (3) which IDs are returned for chaining (e.g., decision_id, progress_id), and (4) what pagination metadata is included (total_count, has_more, next_cursor). Example: 'get_decisions returns {decisions: [{id: string, summary: string, tags: string[], created_at: ISO8601}], total_count: number}'.
Expand tool descriptions to include 'WHEN to use this tool' and 'WHAT TO DO ON ERROR'. For example, update get_decisions description to: 'Retrieves all logged decisions for a workspace. Use this when you need the full decision history. If no decisions exist, the list will be empty, consider logging one with log_decision() first. If workspace_id is invalid, call detect_workspace() to find the correct path.'
Add natural-language fallback for workspace_id. Either: (a) document that detect_workspace() can be called first to find the workspace path, or (b) extend tools to accept workspace_name in addition to workspace_id, or (c) set up a server-wide workspace context so workspace_id is optional after initialization. Mention this in descriptions: 'If you don't know the workspace path, call detect_workspace(start_path) first.'
For search tools, clarify when to use each variant. Add to descriptions: search_decisions_fts should be used for 'exact phrase or keyword matching'; search_decisions_semantic should be used for 'similarity-based searches (e.g., "decisions about performance improvements")'. Include a note that FTS is faster for keywords, semantic is better for conceptual queries.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 63 points across a rubric change (v1 → v2)
63/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
C
63
<=2025-11-25
v2
2026-03-09
F
0
-
v1
write50/100
Creates a relationship link between two context items (decisions, progress, patterns, etc.).
log_decisionwritesource verified83/100
Logs a decision with summary, rationale, implementation details, and tags for tracking project decisions.
log_progresswritesource verified83/100
Logs progress on work items with status, description, and optional parent relationship.
log_system_patternwritesource verified81/100
Logs a system design pattern or architectural pattern for reference.
retrieve_custom_dataread only50/100
Retrieves custom data by category and optional key.
Searches decisions using full-text search (FTS) with support for column-specific queries.
search_decisions_semanticread only50/100
Searches decisions using semantic similarity based on vector embeddings.
store_custom_datawrite50/100
Stores arbitrary custom data with category and key-value pairs.
update_active_contextwritesource verified78/100
Updates the active context. Accepts full `content` (object) or `patch_content` (object) for partial updates.
update_product_contextwritesource verified80/100
Updates the product context. Accepts full `content` (object) or `patch_content` (object) for partial updates (use `__DELETE__` as a value in patch to remove a key).
Generic descriptions lack LLM-specific guidance. Tool descriptions are functional (10-160 chars, within 10-1024 range) but do not explain WHEN to choose between similar tools. For example, get_decisions vs search_decisions_fts vs search_decisions_semantic lack guidance on which to use for different user intents ('Give me decisions affecting performance' → semantic search; 'Find decisions mentioning Redis' → FTS; 'Show me my latest decisions' → get_decisions with limit).
workspace_id appears in every tool but is not marked as a natural identifier. The description 'Identifier for the workspace (e.g., absolute path)' suggests users provide paths, but the tool does not accept workspace names or auto-detect. The detect_workspace tool exists but is optional, creating friction. Consider making workspace_id optional with auto-detection fallback or accepting both workspace_id and workspace_name.
No pagination documented for get_decisions, get_progress, get_system_patterns. These tools likely return lists but descriptions do not mention limit/offset parameters or indicate if results are capped. Without pagination, large result sets risk exhausting context windows. Descriptions should state 'Returns up to N results; use limit parameter to control size' or similar.
Search tools (search_decisions_fts, search_decisions_semantic) lack guidance on syntax and capabilities. The FTS tool description mentions 'FTS5 syntax' but does not explain what that means for an LLM user (boolean operators, wildcards, field prefixes?). Semantic search mentions min_similarity but doesn't explain how it works or what values mean what.
search_decisions_ftssearch_decisions_semantic
Specify result limits in descriptions. For get_decisions, get_progress, and get_system_patterns, state: 'Returns up to [limit] results (default 20). Use limit parameter to retrieve more.' This prevents context-window surprises.
Add error scenarios to descriptions. For example, log_decision description could add: 'Returns the new decision ID on success. If the workspace does not exist, returns an error with a suggestion to use detect_workspace() or create the workspace first.'
Consider adding idempotentHint and destructiveHint tool annotations. Tools like log_decision, log_progress, and log_system_pattern are idempotent (calling with the same input twice is safe). Tools like update_product_context and update_active_context are destructive (patch operations can lose data). Mark these in tool definitions to help agents reason about retry safety.
Document the relationship between update_product_context and update_active_context. Both accept content or patch_content, add a note explaining: 'product_context is the long-term project blueprint; active_context is the current focus. They are independent. Use product_context for architecture decisions and features; use active_context for in-progress work.'
For link_context_items, document valid relationship_type values. The description mentions 'e.g., implements, depends_on, blocks' but doesn't state if these are the only options or if custom types are allowed. Add: 'relationship_type can be: implements, depends_on, blocks, references, contradicts, or any custom string you define.'
Add guidance on custom_data usage. The store_custom_data and retrieve_custom_data tools are generic, add descriptions that explain the use case: 'Use to store metadata that doesn't fit other tools (e.g., team preferences, experimental settings). category groups related data; key is the name within that category.'
Consider adding a tool to delete or archive decisions, progress, and patterns. Currently, only read and write are supported, there's no way to clean up old entries or mark them as superseded. This limits long-term context management.