Generic MCP server for document research using Pinecone Assistant API - Zero-token conversational research with customizable domains
The server provides 7 tools with reasonably detailed descriptions and parameter schemas. However, there are significant gaps: (1) tool names lack consistent action-verb prefixes (e.g., 'assistant_context' vs 'get_context'), (2) several parameter descriptions are generic or lack usage guidance, (3) output schemas are not explicitly documented in the code, (4) no tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present despite clear risk profiles, and (5) error handling and recovery guidance are minimal. The descriptions are longer than baseline (194 chars avg) but often include API-specific jargon and cost information that could be stripped to focus on LLM-facing semantics. Parameter schemas are present and mostly well-typed, but composition issues exist: tools like 'assistant_chat' and 'assistant_strategic_multi_search_chat' perform very similar operations (synthesis vs context retrieval), risking LLM confusion.
AI-powered synthesis using Pinecone Assistant's built-in LLM. **Token Cost**: Uses input tokens (~0.5-1K) + output tokens (~0.5-2K). Free tier: 1.5M input / 200K output lifetime. **Returns**: Natural language answer synthesized from documents by Pinecone's LLM. **Best for**: Questions requiring AI reasoning and synthesis (e.g., "How do courts assess Section 101 eligibility?"). **When to use instead of assistant_context**: - You need AI to synthesize across multiple documents - You want a natural language answer, not raw chunks - Your token budget allows input+output tokens **Parameters**: - query: Question for AI synthesis - top_k: Number of context chunks (1-64, default: 10) - snippet_size: Tokens per chunk (512-8192, default: 2048) - chat_history: Previous turns (messages array) - multimodal: Include image context (API default: true) - include_binary_content: Include base64 images (API default: true) **Example**: assistant_chat( query: "How do I file a continuation application?", top_k: 10, chat_history: [...] )
⭐ START HERE - Retrieve raw document chunks without AI processing. **Token Cost**: Uses context tokens (Free tier: 500K lifetime, does NOT reset monthly). ~5-10K per query. **Returns**: Raw document snippets with relevancy scores and source references. No AI synthesis - perfect for custom analysis in your host LLM. **Best for**: Most queries. Try this first before AI-powered tools. **Parameters**: - query: What to search for (required unless messages provided) - top_k: Number of chunks (1-64, default: 5) - snippet_size: Tokens per chunk (512-8192, default: 2048) - filter: Optional metadata filtering - multimodal: Retrieve image context from PDFs (API default: true, query-only) - include_binary_content: Include base64 image data (API default: true, query-only, set false to reduce size) - messages: Multi-turn messages as alternative to query (multimodal params ignored when using messages) **Example**: assistant_context( query: "Section 101 eligibility standards", top_k: 5, snippet_size: 2048 )
Tool names lack consistent action-verb prefixes. Names like 'assistant_context', 'assistant_chat', and 'update_configuration' do not follow verb_noun convention. Better: 'get_context', 'search_context', 'get_chat_answer', 'set_configuration'. LLMs rely on verb prefixes to parse intent, inconsistent naming forces extra reasoning.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk profiles. 'update_configuration' has risk=WRITE but no destructiveHint in schema. 'evaluate_answer' is marked READ_ONLY but no readOnlyHint. Per MCP 2026-07-28, tool annotations must be present in tool definition for agents to reason about safety and idempotency.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 59 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 39 | - | v1 |
AI synthesis using multiple search strategies with Pinecone Assistant's LLM. **Use when**: You need comprehensive AI-synthesized answer from multiple search angles. **Token Cost**: Uses input (~1-2K) + output (~1-3K) tokens. Free tier: 1.5M input / 200K output lifetime. **Returns**: Natural language answer synthesized from multi-strategy results. **Parameters**: - domain: Knowledge domain from YAML config (required) - base_query: Core question (required) - top_k_per_strategy: Context chunks per strategy (1-64, default: 5) - snippet_size: Tokens per chunk (512-8192, default: 2048) - strategy_override: Force specific strategies (optional) - chat_history: Previous turns (optional) **Example**: assistant_strategic_multi_search_chat( domain: "patent_procedures", base_query: "What are the requirements for filing a continuation application?", top_k_per_strategy: 5 )
Search documents using multiple pre-defined search strategies from YAML configuration. **Use when**: You need comprehensive coverage from multiple angles (e.g., search for "design patterns" + "implementation" + "edge cases"). **Token Cost**: Similar to assistant_context (~5-10K per query). **Returns**: Raw document snippets from each strategy, labeled with strategy used. **Parameters**: - domain: Knowledge domain from YAML config (required) - base_query: Core search query (required) - top_k_per_strategy: Results per strategy (1-64, default: 3) - snippet_size: Tokens per chunk (512-8192, default: 2048) - strategy_override: Force specific strategies (optional) **Example**: assistant_strategic_multi_search_context( domain: "patent_procedures", base_query: "continuation filing requirements", top_k_per_strategy: 3 )
Evaluate the quality and relevance of a generated answer against the retrieved documents. ⚠️ **PAID FEATURE**: Requires Pinecone paid plan (free tier cannot use this tool). **Use when**: You want quality assurance on synthesized answers. **Returns**: Quality score and relevance assessment with suggestions for improvement. **Parameters**: - answer: Generated answer text to evaluate (required) - query: Original query (required) - context_chunks: Retrieved document chunks (required) - evaluation_criteria: Custom criteria (optional, default: relevance + accuracy) **Example**: evaluate_answer( answer: "Continuation applications are filed using Form XYZ...", query: "How do I file a continuation application?", context_chunks: [...] )
Retrieve current assistant configuration, model, domain, and token usage. **Token Cost**: None (metadata-only, free). **Returns**: Current configuration details and token budget status. **Use case**: Check which assistant is active and see remaining token budget. **Example**: get_configuration_status()
Switch to a different Pinecone Assistant or update model/domain configuration. **Use when**: You want to change which assistant the server uses. **Token Cost**: None (metadata-only operation). **Returns**: Confirmation of new configuration. **Parameters**: - assistant_name: Name of assistant to switch to (required) - assistant_host: Optional host URL (auto-detected if omitted) - model_id: Optional model override - domain: Optional domain context **Example**: update_configuration( assistant_name: "my-other-assistant" )
No output schemas documented. Tool descriptions mention what is returned (e.g., 'Natural language answer', 'Raw document snippets') but the code does not show explicit output schema definitions. LLMs cannot plan downstream calls without knowing what fields to expect. Output schema must be present in tool definition.
Tool composition risks. 'assistant_context' and 'assistant_strategic_multi_search_context' both retrieve raw documents; 'assistant_chat' and 'assistant_strategic_multi_search_chat' both synthesize answers. The distinction (single-strategy vs multi-strategy) is subtle and could confuse LLMs into selecting the wrong tool. Descriptions say 'Use when you need comprehensive coverage' vs 'Use when you need AI reasoning' but the boundary is not crisp.
Error handling lacks recovery guidance. The code includes exception types (AuthenticationError, RateLimitError, etc.) but tool descriptions do not explain what errors can occur or what the LLM should do. E.g., 'evaluate_answer' says 'PAID FEATURE' but does not describe the error response if called on free tier.
Parameter descriptions include API-level jargon and cost information (e.g., 'Uses context tokens (~5-10K per query), Free tier: 500K lifetime') that bloats descriptions and obscures the core function. Trim to focus on parameter semantics; move cost info to tool-level documentation.
Parameter 'filter' in 'assistant_context' has type=object with no properties schema. What keys does it accept? What types do values have? Underdefined schemas force LLMs to guess or fail.
Parameter 'messages' and 'chat_history' are arrays with no item schema. What fields does each message object contain? (e.g., 'role', 'content', 'timestamp'). Undefined array schemas prevent LLMs from constructing valid payloads.
Parameter 'evaluation_criteria' in 'evaluate_answer' is an array with no item schema. Unclear whether items are strings (enum values) or objects with fields. LLM cannot construct valid input.
No mutual-exclusivity documentation. In 'assistant_context', 'query' is optional if 'messages' provided, but this is not stated in parameter descriptions. Similarly, 'multimodal' and 'include_binary_content' are 'query-only' (ignored for 'messages' mode), this should be explicitly documented.