Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
6 tools with mixed definition quality. Tool naming follows verb_noun convention (crawl_and_index, search_documents, index_text, health_check, get_stats, export_all) which is good for LLM parsing. Descriptions are present and mostly actionable (58 - 180 chars), exceeding the 20-char floor. However, several critical gaps emerge: (1) Tool 'crawl_and_index' combines two distinct responsibilities (crawl + index) in one name, violating single-responsibility principle. (2) Parameter descriptions lack specificity, e.g., 'URL to crawl' doesn't specify format constraints or examples; 'chunk_size' lacks guidance on valid ranges or performance tradeoffs. (3) Output schemas are partially visible in response models (CrawlResponse, SearchResponse) but lack documentation of what fields downstream tools need. (4) Error handling is minimal, HTTPException returns raw strings without recovery guidance. (5) No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are visible in the code, missing important agent planning hints. Overall, definitions are functional but not LLM-optimized.
Tools (6)
crawl_and_indexwriteauthsource verified60/100
Crawl a URL and index content in ChromaDB
export_allread onlyauthsource verified68/100
Export chunks from ChromaDB with pagination.
get_statsread onlyauthsource verified65/100
Get collection statistics
health_checkread onlysource verified78/100
Health check endpoint
index_textwriteauthsource verified77/100
Index text content directly without crawling. Useful for indexing local files, transcriptions, etc.
Tool 'crawl_and_index' violates single-responsibility principle, combines URL crawling and content indexing. Should split into 'crawl_page' and 'index_content' so agents can compose them flexibly.
Output schemas not fully documented. SearchResponse, CrawlResponse models exist in code but descriptions of returned fields (metadata structure, distance units, chunks_added semantics) are absent. Downstream tools cannot reliably consume outputs.
Split 'crawl_and_index' into two tools: 'crawl_page(url, max_depth) -> chunks' and 'index_chunks(chunks, title, source, chunk_size) -> success, count'. Allows agents to crawl once, transform, then index, or index from other sources without crawling.
Add min/max constraints to all numeric parameters in schema. E.g., chunk_size: min=100, max=4000 (with rationale in description); n_results: min=1, max=100 (default 5); export_all limit: min=1, max=100 (default 20). Include these bounds in parameter descriptions: 'Size of text chunks (100 - 4000 chars; affects semantic coherence and cost)'.
Document all output field schemas. For SearchResponse: explain metadata structure ('metadata contains source_url, chunk_index, title as strings'), distance semantics ('distance is cosine similarity, 0 - 1; lower = more relevant'). For CrawlResponse: clarify chunks_added meaning and any partial-success scenarios.
Enhance error responses with recovery guidance. Replace 'ChromaDB connection failed: <msg>' with: 'ChromaDB unavailable (retryable). Verify CHROMA_URL env var and network. Retry in 5s.' For crawl failures: 'Unable to extract text from URL (possible: invalid URL, JavaScript-heavy page, rate-limited). Try manual index_text() instead.'
Add tool annotations to all definitions. Mark crawl_and_index and index_text with destructiveHint=true (they modify ChromaDB state). Mark search_documents, health_check, get_stats, export_all with readOnlyHint=true. Mark index_text with idempotentHint=true (re-indexing same content is safe).
Error handling returns raw HTTPException strings without recovery guidance. 'ChromaDB connection failed: <error>' tells agent nothing about retryability or next steps. Should categorize errors (retryable, user-fixable, fatal) and suggest alternatives.
No tool annotations visible. Neither readOnlyHint, destructiveHint, nor idempotentHint are present in tool definitions. This prevents agent planners from understanding retry safety and side-effect scope. crawl_and_index and index_text are write operations requiring explicit marking.
export_all default limit (1000) is excessive for LLM context windows and violates result-capping best practice. Agents cannot reason over 1000 chunks efficiently. Should default to 20 - 50 with documented hard cap.
'health_check' and 'get_stats' descriptions are too terse (20 - 28 chars). Lack context about purpose, when to call, or what 'healthy' status means. Should explain: Why call this? What do results indicate about ChromaDB state?
health_checkget_stats
Lower export_all default limit to 20 - 50. Change: limit: min=1, max=100, default=20. Document: 'Large exports harm agent reasoning. This tool caps at 100 items; use offset pagination for full exports. Recommended: limit ≤ 50.'
Expand terse descriptions. health_check: 'Verify ChromaDB connectivity and collection readiness. Call before crawl/search operations to detect downtime or misconfiguration.' get_stats: 'Return collection metadata: item count, last update. Use to gauge indexing progress or diagnose empty collection issues.'
Add parameter interdependency documentation. For crawl_and_index: 'larger max_depth (>2) increases latency and token cost; typical crawl depth is 1 - 2 for documentation sites. chunk_size affects semantic search quality, 500 - 1500 chars is optimal for most text.'
Return pagination cursors in export_all response. Add 'has_more: boolean' and 'next_offset: int' fields so agents know when to paginate. Current response doesn't indicate whether all items were returned.
Document when to use search_documents vs export_all for agents. E.g., in description: 'For semantic search (recommended), use search_documents(query). For keyword/metadata filtering or full export, use export_all() with pagination.'