From 70527f2b104c6eafc3850579ea27367957519cc8 Mon Sep 17 00:00:00 2001 From: Cody McCabe Date: Thu, 16 Apr 2026 16:17:46 -0400 Subject: [PATCH 1/2] fix: improve command descriptions for LLM tool discoverability (round 2) Target three eval failures (transfers 0%, portfolio 0%, webhooks-create 67%): - wallet address: add explicit deflections to transfers/portfolio/nfts - transfers: lead with "transfer history", add USE WHEN pattern - balance: deflect to portfolio tokens for multi-network queries - portfolio tokens: lead with cross-network signal, add USE WHEN pattern - webhooks create: amplify write/create signal with (write operation) - webhooks list: strengthen read-only contrast with create Co-Authored-By: Claude Sonnet 4.6 (1M context) --- src/commands/balance.ts | 2 +- src/commands/portfolio.ts | 2 +- src/commands/transfers.ts | 2 +- src/commands/wallet.ts | 2 +- src/commands/webhooks.ts | 4 ++-- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/commands/balance.ts b/src/commands/balance.ts index 14f089a..241e20b 100644 --- a/src/commands/balance.ts +++ b/src/commands/balance.ts @@ -67,7 +67,7 @@ export function registerBalance(program: Command) { .command("balance") .argument("[address]", "Wallet address (0x...) or ENS name, or pipe via stdin") .alias("bal") - .description("Returns the native token balance (ETH, MATIC, etc.) for any wallet address or ENS name. Use when the user wants to know how much native currency a wallet holds. Does NOT return ERC-20 tokens — use `alchemy tokens balances` for that.") + .description("Returns the native token balance (ETH, MATIC, etc.) for a single address on the current network. Use for 'how much ETH does this wallet have' queries only. Does NOT return ERC-20 tokens or multi-network portfolio data — use `alchemy tokens balances` for ERC-20s, or `alchemy portfolio tokens` for a full cross-network portfolio overview.") .addHelpText( "after", ` diff --git a/src/commands/portfolio.ts b/src/commands/portfolio.ts index 13dbb62..bfcfbc3 100644 --- a/src/commands/portfolio.ts +++ b/src/commands/portfolio.ts @@ -24,7 +24,7 @@ export function registerPortfolio(program: Command) { cmd .command("tokens") - .description("Returns all ERC-20 token holdings and their USD values across one or more networks for a wallet address. Use for a portfolio view of fungible token assets. For a single-network NFT list, use `alchemy nfts`; for native token balance, use `alchemy balance`.") + .description("Returns a full cross-network portfolio of all ERC-20 token holdings and USD values for a wallet address. USE WHEN: user asks for portfolio overview, all tokens held, or assets across multiple networks. For NFTs only, use `alchemy nfts`. For native ETH balance only, use `alchemy balance`.") .requiredOption("--body ", "JSON body for /assets/tokens/by-address") .action(async (opts: { body: string }) => { try { diff --git a/src/commands/transfers.ts b/src/commands/transfers.ts index 308cd75..3d5f15c 100644 --- a/src/commands/transfers.ts +++ b/src/commands/transfers.ts @@ -57,7 +57,7 @@ export function registerTransfers(program: Command) { program .command("transfers") .argument("[address]", "Wallet address or ENS name — queries outgoing transfers (use --to-address for incoming)") - .description("Lists all asset transfer transactions for a wallet address — ERC-20, ERC-721, ERC-1155, and native (ETH) transfers. Use for transaction history or transfer activity. Does NOT return current balances — use `alchemy balance` or `alchemy tokens balances` for that.") + .description("Retrieves transfer history — all inbound and outbound asset movements (ERC-20, ERC-721, ERC-1155, and native ETH) for a wallet address. USE WHEN: user asks for transaction history, past transfers, or asset movements. Does NOT return current balances — use `alchemy balance` or `alchemy tokens balances` for that.") .option("--from-address
", "Filter sender address") .option("--to-address
", "Filter recipient address") .option("--from-block ", "Start block (default: 0x0)") diff --git a/src/commands/wallet.ts b/src/commands/wallet.ts index 3df2e57..7dd5470 100644 --- a/src/commands/wallet.ts +++ b/src/commands/wallet.ts @@ -110,7 +110,7 @@ export function registerWallet(program: Command) { cmd .command("address") - .description("Display the address of the locally configured x402 wallet. This shows the CLI's own signing wallet only — it does NOT look up arbitrary addresses. To check a wallet's ETH balance, use `alchemy balance`.") + .description("Display the address of the locally configured x402 wallet. This shows the CLI's own signing wallet only — it does NOT look up arbitrary addresses or retrieve wallet history. To check a wallet's ETH balance, use `alchemy balance`. For transfer history, use `alchemy transfers`. For token portfolio, use `alchemy portfolio tokens`. For NFTs owned by a wallet, use `alchemy nfts`.") .action(() => { try { const key = resolveWalletKey(program); diff --git a/src/commands/webhooks.ts b/src/commands/webhooks.ts index d84dd3e..30ae2d3 100644 --- a/src/commands/webhooks.ts +++ b/src/commands/webhooks.ts @@ -30,7 +30,7 @@ export function registerWebhooks(program: Command) { cmd .command("list") - .description("Lists all existing Alchemy webhooks configured for this team. Use to view or audit registered webhooks. Does NOT create webhooks — use `alchemy webhooks create` for that.") + .description("Lists all existing registered Alchemy webhooks (read-only). USE WHEN: user wants to view, see, audit, or check current webhooks. DOES NOT create or modify webhooks — use `alchemy webhooks create` to register a new one.") .action(async () => { try { const token = resolveWebhookApiKey(cmd.opts()); @@ -46,7 +46,7 @@ export function registerWebhooks(program: Command) { cmd .command("create") - .description("Creates a new Alchemy webhook subscription for a given event type (address activity, mined transactions, dropped transactions, etc.). Use this to register a new webhook endpoint. To view existing webhooks, use `alchemy webhooks list`.") + .description("Creates and registers a NEW Alchemy webhook endpoint (write operation). USE WHEN: user wants to set up, add, register, or create a webhook for address activity, mined/dropped transactions, etc. DOES NOT list existing webhooks — use `alchemy webhooks list` for that.") .requiredOption("--body ", "Create webhook JSON payload") .option("--dry-run", "Preview without executing") .action(async (opts: { body: string; dryRun?: boolean }) => { From bdfa4674543ebe05ff53ab403b8de586f924eae3 Mon Sep 17 00:00:00 2001 From: Cody McCabe Date: Thu, 16 Apr 2026 16:22:17 -0400 Subject: [PATCH 2/2] chore: add changeset for description improvements Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .changeset/fix-command-descriptions.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/fix-command-descriptions.md diff --git a/.changeset/fix-command-descriptions.md b/.changeset/fix-command-descriptions.md new file mode 100644 index 0000000..4ecd219 --- /dev/null +++ b/.changeset/fix-command-descriptions.md @@ -0,0 +1,5 @@ +--- +"@alchemy/cli": patch +--- + +Improved command descriptions for `balance`, `transfers`, `portfolio tokens`, `wallet address`, `webhooks list`, and `webhooks create` to reduce ambiguity when tools are used by an LLM agent.