helius-mcp 0.5.3 → 1.2.0

package/dist/tools/blocks.js

@@ -1,100 +1,81 @@
 import { z } from 'zod';
-import { hasApiKey, getRpcUrl } from '../utils/helius.js';
+import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { formatSol, formatTimestamp } from '../utils/formatters.js';
 import { noApiKeyResponse } from './shared.js';
+import { mcpText, validateEnum, handleToolError } from '../utils/errors.js';
 export function registerBlockTools(server) {
-    server.tool('getBlock', 'Get detailed information about a specific Solana block by slot number. Returns block time, blockhash, parent slot, transaction count, and reward summary. Use transactionDetails to control how much transaction data is included: "none" for just block metadata, "signatures" for a list of transaction signatures, or "full" for complete transaction data.', {
+    server.tool('getBlock', 'BEST FOR: inspecting a specific block by slot number. Get detailed information about a specific Solana block by slot number. Returns block time, blockhash, parent slot, transaction count, and reward summary. Use transactionDetails to control how much transaction data is included: "none" for just block metadata, "signatures" for a list of transaction signatures, or "full" for complete transaction data. Credit cost: 10 credits/call (historical data).', {
         slot: z.number().describe('Slot number of the block to fetch'),
-        transactionDetails: z.enum(['none', 'signatures', 'full']).optional().default('signatures').describe('"none" = block metadata only, "signatures" = list of tx signatures (default), "full" = complete transaction data')
+        transactionDetails: z.string().optional().default('signatures').describe('"none" = block metadata only, "signatures" = list of tx signatures (default), "full" = complete transaction data')
     }, async ({ slot, transactionDetails }) => {
         if (!hasApiKey())
             return noApiKeyResponse();
-        const url = getRpcUrl();
-        const requestBody = {
-            jsonrpc: '2.0',
-            id: 'get-block',
-            method: 'getBlock',
-            params: [
-                slot,
-                {
-                    encoding: 'jsonParsed',
-                    transactionDetails,
-                    maxSupportedTransactionVersion: 0,
-                    rewards: true
-                }
-            ]
-        };
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(requestBody)
-        });
-        const data = await response.json();
-        if (data.error) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Error**\n\n${data.error.message}`
-                    }]
-            };
-        }
-        const block = data.result;
-        if (!block) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Block at Slot ${slot.toLocaleString()}**\n\nBlock not found. It may have been skipped or not yet confirmed.`
-                    }]
-            };
-        }
-        const lines = [
-            `**Block at Slot ${slot.toLocaleString()}**`,
-            '',
-            `**Blockhash:** ${block.blockhash}`,
-            `**Parent Slot:** ${block.parentSlot.toLocaleString()}`,
-            `**Previous Blockhash:** ${block.previousBlockhash}`,
-        ];
-        if (block.blockHeight !== null) {
-            lines.push(`**Block Height:** ${block.blockHeight.toLocaleString()}`);
-        }
-        if (block.blockTime) {
-            lines.push(`**Block Time:** ${formatTimestamp(block.blockTime)}`);
-        }
-        // Transaction count
-        if (transactionDetails === 'signatures' && block.signatures) {
-            lines.push(`**Transactions:** ${block.signatures.length}`);
-        }
-        else if (transactionDetails === 'full' && block.transactions) {
-            lines.push(`**Transactions:** ${block.transactions.length}`);
-        }
-        // Rewards summary
-        if (block.rewards && block.rewards.length > 0) {
-            const totalRewards = block.rewards.reduce((sum, r) => sum + r.lamports, 0);
-            const rewardTypes = new Map();
-            block.rewards.forEach((r) => {
-                rewardTypes.set(r.rewardType, (rewardTypes.get(r.rewardType) || 0) + r.lamports);
-            });
-            lines.push('', `**Rewards:** ${formatSol(totalRewards)} total (${block.rewards.length} recipients)`);
-            rewardTypes.forEach((lamports, type) => {
-                lines.push(`- ${type}: ${formatSol(lamports)}`);
-            });
-        }
-        // Show signatures if in signatures mode
-        if (transactionDetails === 'signatures' && block.signatures && block.signatures.length > 0) {
-            const maxShow = 20;
-            lines.push('', `**Transaction Signatures** (${block.signatures.length} total):`);
-            block.signatures.slice(0, maxShow).forEach((sig) => {
-                lines.push(`- ${sig}`);
+        const err = validateEnum(transactionDetails, ['none', 'signatures', 'full'], 'Block Error', 'transactionDetails');
+        if (err)
+            return err;
+        try {
+            const helius = getHeliusClient();
+            // Kit requires BigInt for slot parameter
+            const block = await helius.getBlock(BigInt(slot), {
+                encoding: 'jsonParsed',
+                transactionDetails,
+                maxSupportedTransactionVersion: 0,
+                rewards: true
             });
-            if (block.signatures.length > maxShow) {
-                lines.push(`... +${block.signatures.length - maxShow} more`);
+            if (!block) {
+                return mcpText(`**Block at Slot ${slot.toLocaleString()}**\n\nBlock not found. It may have been skipped or not yet confirmed.`);
+            }
+            const parentSlot = Number(block.parentSlot);
+            const blockHeight = block.blockHeight != null ? Number(block.blockHeight) : null;
+            const blockTime = block.blockTime != null ? Number(block.blockTime) : null;
+            const lines = [
+                `**Block at Slot ${slot.toLocaleString()}**`,
+                '',
+                `**Blockhash:** ${block.blockhash}`,
+                `**Parent Slot:** ${parentSlot.toLocaleString()}`,
+                `**Previous Blockhash:** ${block.previousBlockhash}`,
+            ];
+            if (blockHeight !== null) {
+                lines.push(`**Block Height:** ${blockHeight.toLocaleString()}`);
+            }
+            if (blockTime) {
+                lines.push(`**Block Time:** ${formatTimestamp(blockTime)}`);
+            }
+            // Transaction count
+            if (transactionDetails === 'signatures' && block.signatures) {
+                lines.push(`**Transactions:** ${block.signatures.length}`);
+            }
+            else if (transactionDetails === 'full' && block.transactions) {
+                lines.push(`**Transactions:** ${block.transactions.length}`);
             }
+            // Rewards summary
+            if (block.rewards && block.rewards.length > 0) {
+                const totalRewards = block.rewards.reduce((sum, r) => sum + Number(r.lamports), 0);
+                const rewardTypes = new Map();
+                block.rewards.forEach((r) => {
+                    const lamports = Number(r.lamports);
+                    rewardTypes.set(r.rewardType, (rewardTypes.get(r.rewardType) || 0) + lamports);
+                });
+                lines.push('', `**Rewards:** ${formatSol(totalRewards)} total (${block.rewards.length} recipients)`);
+                rewardTypes.forEach((lamports, type) => {
+                    lines.push(`- ${type}: ${formatSol(lamports)}`);
+                });
+            }
+            // Show signatures if in signatures mode
+            if (transactionDetails === 'signatures' && block.signatures && block.signatures.length > 0) {
+                const maxShow = 20;
+                lines.push('', `**Transaction Signatures** (${block.signatures.length} total):`);
+                block.signatures.slice(0, maxShow).forEach((sig) => {
+                    lines.push(`- ${sig}`);
+                });
+                if (block.signatures.length > maxShow) {
+                    lines.push(`... +${block.signatures.length - maxShow} more`);
+                }
+            }
+            return mcpText(lines.join('\n'));
+        }
+        catch (err) {
+            return handleToolError(err, 'Error fetching block');
         }
-        return {
-            content: [{
-                    type: 'text',
-                    text: lines.join('\n')
-                }]
-        };
     });
 }

package/dist/tools/config.js

@@ -1,98 +1,37 @@
 import { z } from 'zod';
 import { setApiKey, setNetwork, hasApiKey, getHeliusClient } from '../utils/helius.js';
+import { mcpText, validateEnum, getErrorMessage } from '../utils/errors.js';
+import { setSharedApiKey, SHARED_CONFIG_PATH } from '../utils/config.js';
 export function registerConfigTools(server) {
-    // Check API key status tool - always works, helps users understand state
-    server.tool('getHeliusApiKeyStatus', 'Check if a Helius API key is configured. Use this to see if you need to set an API key before using data tools.', {}, async () => {
-        const hasKey = hasApiKey();
-        const fromEnv = !!process.env.HELIUS_API_KEY;
-        if (hasKey) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: fromEnv
-                            ? 'API key is configured via environment variable. Ready to use all Helius tools.'
-                            : 'API key is configured for this session. Ready to use all Helius tools.'
-                    }]
-            };
-        }
-        return {
-            content: [{
-                    type: 'text',
-                    text: [
-                        'No Helius API key configured.',
-                        '',
-                        'To use Helius data tools, you need to set an API key:',
-                        '',
-                        '**Option 1: Use setHeliusApiKey tool**',
-                        '```',
-                        'Tool: setHeliusApiKey',
-                        'Arguments: { "apiKey": "your-api-key" }',
-                        '```',
-                        '',
-                        '**Option 2: Set environment variable**',
-                        'Add to your MCP config:',
-                        '```',
-                        '"env": { "HELIUS_API_KEY": "your-api-key" }',
-                        '```',
-                        '',
-                        '**Get your free API key at: https://dashboard.helius.dev/api-keys**',
-                        '',
-                        'Note: Guide tools (getRateLimitInfo, getSenderInfo, etc.) work without an API key.',
-                    ].join('\n')
-                }]
-        };
-    });
-    server.tool('setHeliusApiKey', 'Set the Helius API key for the current session. Required before using data tools (getBalance, getAsset, etc.). Get your free API key at https://dashboard.helius.dev/api-keys', {
+    const keyFromEnv = hasApiKey();
+    server.tool('setHeliusApiKey', keyFromEnv
+        ? 'API key is already configured via environment. You do NOT need to call this tool - just use the other Helius tools directly.'
+        : 'Set an existing Helius API key for the current session. If the user does not have a key, use the agentic signup flow instead: generateKeypair → fund wallet → agenticSignup. Get a key at https://dashboard.helius.dev/api-keys', {
         apiKey: z.string().describe('Your Helius API key from https://dashboard.helius.dev/api-keys'),
-        network: z.enum(['mainnet', 'devnet']).optional().default('mainnet').describe('Network to use (default: mainnet)')
+        network: z.string().optional().default('mainnet-beta').describe('Network to use (default: mainnet-beta)')
     }, async ({ apiKey, network }) => {
+        const err = validateEnum(network, ['mainnet-beta', 'devnet'], 'API Key Error', 'network');
+        if (err)
+            return err;
+        if (hasApiKey() && process.env.HELIUS_API_KEY) {
+            return mcpText(`✅ API key is already configured via environment. You don't need to set it - just use the other Helius tools directly (getBalance, parseTransactions, getAsset, etc.)`);
+        }
         setApiKey(apiKey);
         if (network) {
             setNetwork(network);
         }
-        // Validate the key by making a simple request
         try {
             const helius = getHeliusClient();
             await helius.getBlockHeight();
         }
-        catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
+        catch (e) {
+            const errorMsg = getErrorMessage(e);
             if (errorMsg.includes('invalid api key') || errorMsg.includes('401') || errorMsg.includes('Unauthorized')) {
                 setApiKey('');
-                return {
-                    content: [{
-                            type: 'text',
-                            text: [
-                                'Invalid API key. The key was rejected by the Helius API.',
-                                '',
-                                'Please check your key and try again.',
-                                '',
-                                'Get your free API key at: https://dashboard.helius.dev/api-keys',
-                            ].join('\n')
-                        }],
-                    isError: true
-                };
+                return mcpText(`❌ Invalid API key. Please check your key and try again.\n\nGet your key at https://dashboard.helius.dev/api-keys`);
             }
         }
-        return {
-            content: [{
-                    type: 'text',
-                    text: [
-                        `Helius API key configured. (default network: ${network})`,
-                        '',
-                        'Your API key works for both mainnet and devnet. To switch networks:',
-                        '- mainnet: https://mainnet.helius-rpc.com/?api-key=YOUR_KEY',
-                        '- devnet: https://devnet.helius-rpc.com/?api-key=YOUR_KEY',
-                        '',
-                        'You can now use all Helius tools:',
-                        '- getBalance, getTokenBalances - Check wallet balances',
-                        '- getAsset, searchAssets - Query NFTs and tokens',
-                        '- parseTransactions - Decode transaction history',
-                        '- getWalletHistory, getWalletIdentity - Wallet analysis',
-                        '- createWebhook, getAllWebhooks - Manage webhooks',
-                        '- And many more! Ask me anything about Solana.',
-                    ].join('\n')
-                }]
-        };
+        setSharedApiKey(apiKey);
+        return mcpText(`✅ Helius API key configured for ${network} and saved to \`${SHARED_CONFIG_PATH}\`. You can now query the Solana blockchain.`);
     });
 }

package/dist/tools/das-extras.js

@@ -1,54 +1,60 @@
 import { z } from 'zod';
-import { dasRequest } from '../utils/helius.js';
+import { getHeliusClient, hasApiKey } from '../utils/helius.js';
 import { formatAddress } from '../utils/formatters.js';
+import { mcpText, mcpError, handleToolError, addressError, notFoundError, paginationError } from '../utils/errors.js';
+import { noApiKeyResponse } from './shared.js';
 export function registerDasExtraTools(server) {
-    server.tool('getAssetProof', 'Get Merkle proof for a compressed NFT. Required for transferring or burning cNFTs.', {
-        id: z.string().describe('Compressed NFT mint address')
+    server.tool('getAssetProof', 'BEST FOR: getting Merkle proof required for transferring or burning a cNFT. PREFER getAssetProofBatch when you need proofs for multiple cNFTs. Get Merkle proof for a compressed NFT. Required for transferring or burning cNFTs. DAS API (10 credits/call).', {
+        id: z.string().describe('Compressed NFT mint address (base58 encoded)')
     }, async ({ id }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
         try {
-            const proof = await dasRequest('getAssetProof', { id });
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Merkle Proof for ${formatAddress(id)}**\n\n**Root:** ${formatAddress(proof.root)}\n**Leaf:** ${formatAddress(proof.leaf)}\n**Tree ID:** ${formatAddress(proof.tree_id)}\n**Proof Length:** ${proof.proof.length} nodes`
-                    }]
-            };
+            const helius = getHeliusClient();
+            const proof = await helius.getAssetProof({ id });
+            return mcpText(`**Merkle Proof for ${formatAddress(id)}**\n\n**Root:** ${formatAddress(proof.root)}\n**Leaf:** ${formatAddress(proof.leaf)}\n**Tree ID:** ${formatAddress(proof.tree_id)}\n**Proof Length:** ${proof.proof.length} nodes`);
         }
         catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }], isError: true };
+            const header = `Merkle Proof for ${formatAddress(id)}`;
+            return handleToolError(err, 'Error fetching asset proof', [
+                notFoundError(header, 'Asset proof not found. This asset may not be a compressed NFT (cNFT), or the mint address does not exist.'),
+                addressError(header, 'Invalid Solana address. Please provide a valid base58-encoded mint address.'),
+            ]);
         }
     });
-    server.tool('getAssetProofBatch', 'Get Merkle proofs for multiple compressed NFTs in one request (up to 1000).', {
-        ids: z.array(z.string()).describe('Array of cNFT mint addresses (up to 1000)')
+    server.tool('getAssetProofBatch', 'BEST FOR: batch Merkle proofs for multiple cNFT operations. PREFER getAssetProof for a single cNFT. Get Merkle proofs for multiple compressed NFTs in one request (up to 1000). DAS API (10 credits/call).', {
+        ids: z.array(z.string()).describe('Array of cNFT mint addresses (base58 encoded, up to 1000)')
     }, async ({ ids }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
         try {
             if (ids.length > 1000) {
-                return { content: [{ type: 'text', text: 'Max 1000 proofs per batch' }], isError: true };
+                return mcpError('Max 1000 proofs per batch');
             }
-            const result = await dasRequest('getAssetProofBatch', { ids });
+            const helius = getHeliusClient();
+            const result = await helius.getAssetProofBatch({ ids });
             const proofsArray = Array.isArray(result) ? result : Object.values(result);
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Batch Merkle Proofs** (${proofsArray.length})\n\n${proofsArray.map((p, i) => `${i + 1}. ${formatAddress(ids[i])}\n   Root: ${formatAddress(p.root)}`).join('\n\n')}`
-                    }]
-            };
+            return mcpText(`**Batch Merkle Proofs** (${proofsArray.length})\n\n${proofsArray.map((p, i) => `${i + 1}. ${formatAddress(ids[i])}\n   Root: ${formatAddress(p.root)}`).join('\n\n')}`);
         }
         catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }], isError: true };
+            return handleToolError(err, 'Error fetching asset proofs', [
+                notFoundError('Batch Merkle Proofs', 'One or more asset proofs were not found. Some assets may not be compressed NFTs (cNFTs), or the mint addresses may not exist.'),
+                addressError('Batch Merkle Proofs', 'One or more provided IDs are not valid Solana addresses. Please check the mint addresses and try again.'),
+            ]);
         }
     });
-    server.tool('getSignaturesForAsset', 'Get transaction history for a compressed NFT.', {
-        id: z.string().describe('Compressed NFT mint address'),
+    server.tool('getSignaturesForAsset', 'BEST FOR: transaction history for a specific asset by mint address. PREFER getTransactionHistory for wallet-level transaction history. Get transaction history for any DAS asset. DAS API (10 credits/call).', {
+        id: z.string().describe('Asset mint address (base58 encoded, any DAS asset)'),
         page: z.number().optional().default(1),
         limit: z.number().optional().default(20)
     }, async ({ id, page, limit }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
         try {
-            const result = await dasRequest('getSignaturesForAsset', { id, page, limit });
+            const helius = getHeliusClient();
+            const result = await helius.getSignaturesForAsset({ id, page, limit });
             if (!result.items?.length) {
-                return { content: [{ type: 'text', text: `**Signatures for ${formatAddress(id)}**\n\nNo transactions found.` }] };
+                return mcpText(`**Signatures for ${formatAddress(id)}**\n\nNo transactions found.`);
             }
             const lines = [`**Signatures for ${formatAddress(id)}** (${result.total} total)`, ''];
             result.items.forEach((sig, i) => {
@@ -56,22 +62,29 @@ export function registerDasExtraTools(server) {
                 if (sig.blockTime)
                     lines.push(`   Time: ${new Date(sig.blockTime * 1000).toLocaleString()}`);
             });
-            return { content: [{ type: 'text', text: lines.join('\n') }] };
+            return mcpText(lines.join('\n'));
         }
         catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }], isError: true };
+            const header = `Signatures for ${formatAddress(id)}`;
+            return handleToolError(err, 'Error fetching signatures', [
+                notFoundError(header, 'Asset not found. This mint address does not exist or has not been indexed.'),
+                addressError(header, 'Invalid Solana address. Please provide a valid base58-encoded mint address.'),
+                paginationError(header),
+            ]);
         }
     });
-    server.tool('getNftEditions', 'Get all edition NFTs for a master NFT.', {
-        mint: z.string().describe('Master NFT mint address'),
+    server.tool('getNftEditions', 'BEST FOR: finding numbered edition prints of a master NFT. Get all edition NFTs for a master NFT. DAS API (10 credits/call).', {
+        mint: z.string().describe('Master NFT mint address (base58 encoded)'),
         page: z.number().optional().default(1),
         limit: z.number().optional().default(20)
     }, async ({ mint, page, limit }) => {
+        if (!hasApiKey())
+            return noApiKeyResponse();
         try {
-            const result = await dasRequest('getNftEditions', { mint, page, limit });
+            const helius = getHeliusClient();
+            const result = await helius.getNftEditions({ mint, page, limit });
             if (!result.editions?.length) {
-                return { content: [{ type: 'text', text: `**Editions for ${formatAddress(mint)}**\n\nNo editions found.` }] };
+                return mcpText(`**Editions for ${formatAddress(mint)}**\n\nNo editions found.`);
             }
             const lines = [`**Editions for ${formatAddress(mint)}** (${result.total} total)`, ''];
             result.editions.forEach((edition, i) => {
@@ -80,14 +93,16 @@ export function registerDasExtraTools(server) {
                 if (edition.owner)
                     lines.push(`   Owner: ${formatAddress(edition.owner)}`);
             });
-            return { content: [{ type: 'text', text: lines.join('\n') }] };
+            return mcpText(lines.join('\n'));
         }
         catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            if (errorMsg.includes('null value was encountered while decoding')) {
-                return { content: [{ type: 'text', text: `**Editions for ${formatAddress(mint)}**\n\nThis mint is not a master edition NFT. getNftEditions only works with master edition mints.` }] };
-            }
-            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }], isError: true };
+            const header = `Editions for ${formatAddress(mint)}`;
+            return handleToolError(err, 'Error fetching editions', [
+                { match: (m) => m.includes('null value was encountered'), respond: () => mcpText(`**${header}**\n\nThis mint is not a master edition NFT. getNftEditions only works with master edition mints.`) },
+                notFoundError(header, 'Asset not found. This mint address does not exist or has not been indexed.'),
+                addressError(header, 'Invalid Solana address. Please provide a valid base58-encoded mint address.'),
+                paginationError(header),
+            ]);
         }
     });
 }

package/dist/tools/docs.js

@@ -1,13 +1,14 @@
 import { z } from 'zod';
-import { fetchDoc, getDocsIndex } from '../utils/docs.js';
+import { fetchDoc, getDocsIndex, extractSections, truncateDoc } from '../utils/docs.js';
 export function registerDocsTools(server) {
     /**
      * Lookup Helius documentation - fetches official docs for accurate information
      */
-    server.tool('lookupHeliusDocs', 'Fetch official Helius documentation for accurate, up-to-date information. Use this when you need precise details about APIs, pricing, rate limits, or features. Returns the official llms.txt documentation which is optimized for AI consumption.', {
+    server.tool('lookupHeliusDocs', 'BEST FOR: API documentation and technical details. NOT for pricing (use getHeliusPlanInfo) or errors (use troubleshootError). Fetch official Helius documentation by topic. Use `section` parameter to fetch only relevant sections and save tokens.', {
         topic: z
             .enum([
             'overview',
+            'agents',
             'billing',
             'das',
             'rpc',
@@ -33,43 +34,12 @@ export function registerDocsTools(server) {
             const content = await fetchDoc(topic);
             // If a section filter is provided, extract relevant parts
             if (section) {
-                const sectionLower = section.toLowerCase();
-                const lines = content.split('\n');
-                const relevantLines = [];
-                let inRelevantSection = false;
-                let sectionDepth = 0;
-                for (const line of lines) {
-                    // Check if this is a header
-                    const headerMatch = line.match(/^(#{1,4})\s+(.+)/);
-                    if (headerMatch) {
-                        const depth = headerMatch[1].length;
-                        const title = headerMatch[2].toLowerCase();
-                        if (title.includes(sectionLower)) {
-                            inRelevantSection = true;
-                            sectionDepth = depth;
-                            relevantLines.push(line);
-                        }
-                        else if (inRelevantSection && depth <= sectionDepth) {
-                            // We've hit a new section at same or higher level
-                            inRelevantSection = false;
-                        }
-                        else if (inRelevantSection) {
-                            relevantLines.push(line);
-                        }
-                    }
-                    else if (inRelevantSection) {
-                        relevantLines.push(line);
-                    }
-                    else if (line.toLowerCase().includes(sectionLower)) {
-                        // Include lines that mention the section keyword even outside headers
-                        relevantLines.push(line);
-                    }
-                }
-                if (relevantLines.length > 0) {
+                const extracted = extractSections(content, section, { includeLooseMatches: true });
+                if (extracted) {
                     const result = [
                         `# Helius Docs: ${topic} (filtered by "${section}")`,
                         '',
-                        ...relevantLines,
+                        extracted,
                         '',
                         '---',
                         `Source: https://www.helius.dev/docs (${topic})`,
@@ -87,14 +57,16 @@ export function registerDocsTools(server) {
                     };
                 }
             }
-            // Return full documentation
+            // Return full documentation (truncated to save tokens)
             const result = [
                 `# Helius Docs: ${topic}`,
                 '',
-                content,
+                truncateDoc(content),
                 '',
                 '---',
                 `Source: https://www.helius.dev/docs`,
+                '',
+                '*Tip: Use the `section` parameter (e.g., section: "rate limits") to fetch only what you need and save tokens.*',
             ].join('\n');
             return { content: [{ type: 'text', text: result }] };
         }
@@ -119,32 +91,18 @@ export function registerDocsTools(server) {
         const lines = [
             '# Available Helius Documentation Topics',
             '',
-            'Use `lookupHeliusDocs` with any of these topics to fetch official documentation:',
+            'Use `lookupHeliusDocs` with any of these topics. Add `section` to filter.',
             '',
             '| Topic | Description |',
             '|-------|-------------|',
             ...index.map((doc) => `| \`${doc.key}\` | ${doc.description} |`),
-            '',
-            '## Usage Examples',
-            '',
-            '```',
-            '// Get overview with plans, credits, rate limits',
-            'lookupHeliusDocs({ topic: "overview" })',
-            '',
-            '// Get DAS API documentation',
-            'lookupHeliusDocs({ topic: "das" })',
-            '',
-            '// Get specific section from docs',
-            'lookupHeliusDocs({ topic: "overview", section: "credits" })',
-            'lookupHeliusDocs({ topic: "das", section: "rate limits" })',
-            '```',
         ];
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     /**
      * Get credits information from official docs
      */
-    server.tool('getHeliusCreditsInfo', 'Get official Helius credit costs from documentation. Fetches the latest pricing information directly from Helius docs.', {}, async () => {
+    server.tool('getHeliusCreditsInfo', 'BEST FOR: credit cost lookup table. PREFER getRateLimitInfo for per-method rate limits, getHeliusPlanInfo for plan pricing. Get official Helius credit costs from documentation.', {}, async () => {
         try {
             const content = await fetchDoc('overview');
             // Extract credits section