fix: improve command descriptions for LLM tool discoverability (round 2)

.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.

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",
       `

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>", "JSON body for /assets/tokens/by-address")
     .action(async (opts: { body: string }) => {
       try {

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 <address>", "Filter sender address")
     .option("--to-address <address>", "Filter recipient address")
     .option("--from-block <block>", "Start block (default: 0x0)")

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);

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 <json>", "Create webhook JSON payload")
     .option("--dry-run", "Preview without executing")
     .action(async (opts: { body: string; dryRun?: boolean }) => {