Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This server has 17 tools with widely inconsistent quality. Naming is generally action-verb compliant (list_, create_, get_, etc.), but several tools lack sufficient parameter descriptions, and critical output schemas are not visible in the provided source. The tools range from simple read operations (chroma_list_collections, chroma_peek_collection) to complex stateful operations (chroma_sequential_thinking, chroma_continue_thought_chain) without clear distinction in naming or error guidance. Parameter descriptions are sparse, most parameters have one-line descriptions but lack constraints, format hints, or actionable validation rules. No return schemas are documented. The 'thought' tools (sequential_thinking, get_similar_sessions, etc.) appear to implement features outside Chroma's standard API but lack detailed explanation of their semantics or output format. Error handling is not visible in the source excerpt provided. No tool uses annotations (readOnlyHint, destructiveHint, idempotentHint) despite several tools being clearly WRITE or DESTRUCTIVE.
Tools (17)
chroma_add_documentswritesource verified65/100
Add documents to a collection with optional embeddings and metadata.
Output schemas are not documented for any tool. The source code shows HTTP endpoint handling and tool registration but provides no return type schemas. LLMs cannot plan downstream tool calls or extract relevant fields without knowing what each tool returns.
Parameter descriptions lack validation constraints, format hints, and range information. E.g., 'limit' parameters have no stated min/max bounds; 'embedding_function_name' lists 6 valid values in the description but does not declare them as an enum. Enums allow LLMs to pick valid options directly; free-form strings invite hallucinated values.
Recommendations
Add JSON Schema definitions (documented in tool definitions or schema files) for every tool's return type. Include field names, types, and descriptions so LLMs know what to expect.
Convert lists of valid values (e.g., embedding_function_name: 'default, cohere, openai, jina, voyageai, roboflow') into enum constraints in the JSON schema. Update descriptions to reference the enum rather than listing options as text.
Expand parameter descriptions to include validation rules. Example: 'limit (integer, 1-100): Maximum number of collections to return. Defaults to 20.' This matches production-baseline pattern (72 chars avg for param descriptions).
Add tool annotations to all tool definitions: mark read-only tools with readOnlyHint=true, destructive tools with destructiveHint=true, and idempotent operations with idempotentHint=true. This requires updating the fastmcp framework registration to include these hints.
Redesign or remove 'thought' tools (chroma_sequential_thinking, chroma_get_similar_sessions, etc.) or provide full documentation. Explain what session/thought semantics are, what data structures are stored, and how they integrate with standard Chroma collections. If these are domain-specific extensions, prefix them clearly or move to a separate tool namespace.
Implement error recovery guidance. When a collection is not found, catch the error and return: 'Collection "xyz" not found. Available collections: [list here]. Try calling chroma_list_collections first.' This helps LLMs self-correct.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↓ 3 points across a rubric change (v1 → v2)
48/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
48
<=2025-11-25
v2
2026-03-09
D
51
-
v1
read onlysource verified62/100
Get documents from a collection by ID or filter conditions.
Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are not applied. Per the tool metadata, chroma_delete_collection and chroma_delete_documents are DESTRUCTIVE, and chroma_add_documents and chroma_update_documents are WRITE operations, but no annotations are visible in the tool definitions. Annotations help LLMs understand safety implications before execution.
'Thought' tools (chroma_sequential_thinking, chroma_get_similar_sessions, chroma_get_thought_history, chroma_get_thought_branches, chroma_continue_thought_chain) have vague, underdescribed semantics. The descriptions do not explain what 'sequential thinking' means, what a 'session' or 'thought_id' represents, or what output structure to expect. These tools appear to implement features beyond standard Chroma vector search but lack sufficient context for LLM selection.
No error handling guidance visible in source. The JSON-RPC endpoint catches exceptions but returns generic error responses without actionable recovery hints. When a collection is not found, the LLM is not told what collections exist or how to proceed. This violates the recovery-guide pattern.
No dry-run or confirmation pattern for destructive operations. chroma_delete_collection and chroma_delete_documents are irreversible but offer no confirmation step or dry-run mode. Agents can mistakenly delete critical data.
Parameter descriptions are generic or minimal. E.g., 'where' and 'where_document' in chroma_query_documents are described as 'Optional filter conditions' with no explanation of syntax, valid operators, or examples. 'include' is 'What to include in results' with no enum of valid options. LLMs cannot use these parameters effectively without clearer guidance.
No pagination enforcement visible. chroma_list_collections accepts limit and offset, but there is no indication of total count, next_cursor, or maximum page size. For large result sets, LLMs may request unbounded data.
The metadata fields in chroma_create_collection (ef_construction, ef_search, max_neighbors, num_threads, batch_size, sync_threshold, resize_factor) lack description text explaining what each parameter controls or what range is valid. These are HNSW-specific tuning knobs but the descriptions do not convey their purpose.
chroma_create_collectionchroma_modify_collection
Add a dry-run parameter to chroma_delete_collection and chroma_delete_documents. E.g., 'dry_run (boolean, default=false): If true, simulate deletion and report what would be deleted without modifying the database.' This prevents accidental data loss.
Document filter syntax for 'where' and 'where_document' parameters. Provide a short example: 'where: {"color": {"$eq": "red"}} or where_document: {"$contains": "keyword"}'. Reference Chroma's filter documentation or include a discovery tool (e.g., chroma_get_filter_syntax).
Add pagination metadata to list responses. Return {"items": [...], "total": 150, "limit": 20, "offset": 0, "has_next": true} so LLMs know when more results are available.
Document HNSW tuning parameters (ef_construction, ef_search, max_neighbors, etc.) with sensible defaults and ranges. Example: 'ef_construction (integer, default=200, range 10-500): Controls HNSW graph construction trade-off. Higher values = slower indexing, better recall.'
Add a 'reason' or 'context' parameter to destructive operations for audit purposes. E.g., chroma_delete_collection(collection_name, reason='...') allows logging why a collection was deleted, aiding compliance and incident investigation.
Provide a chroma_get_collection_schema or similar discovery tool that returns the structure of a collection (field names, embedding dimensions, metadata keys) so agents can plan queries without trial and error.