fix: improve command descriptions for LLM tool discoverability

.changeset/improve-tool-descriptions.md

@@ -0,0 +1,5 @@
+---
+"@alchemy/cli": patch
+---
+
+Improved help text and descriptions for `balance`, `transfers`, `portfolio tokens`, `portfolio nfts`, `nfts`, `simulate asset-changes`, `rpc`, `webhooks list`, `webhooks create`, and `wallet address` to better describe each command's purpose and disambiguate similar commands.

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("Get the native token balance of an address")
+    .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.")
     .addHelpText(
       "after",
       `

src/commands/nfts.ts

@@ -45,7 +45,7 @@ function formatNFTRows(nfts: NFTResponse["ownedNfts"]): string[][] {
 export function registerNFTs(program: Command) {
   const cmd = program
     .command("nfts")
-    .description("NFT API wrappers")
+    .description("Lists all NFTs owned by a wallet address on the current network via the Alchemy NFT API. Use for single-network NFT ownership queries. For all NFTs across multiple networks in a portfolio view, use `alchemy portfolio nfts`.")
     .argument("[address]", "Wallet address or ENS name (default action: list owned NFTs)")
     .option("--limit <n>", "Maximum number of NFTs to return per page", parseInt)
     .option("--page-key <key>", "Pagination key from a previous response")

src/commands/portfolio.ts

@@ -24,7 +24,7 @@ export function registerPortfolio(program: Command) {
 
   cmd
     .command("tokens")
-    .description("Get token portfolio by address/network pairs")
+    .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`.")
     .requiredOption("--body <json>", "JSON body for /assets/tokens/by-address")
     .action(async (opts: { body: string }) => {
       try {
@@ -62,7 +62,7 @@ export function registerPortfolio(program: Command) {
 
   cmd
     .command("nfts")
-    .description("Get NFT portfolio by address/network pairs")
+    .description("Returns all NFTs owned by a wallet address across one or more networks. Use to list all NFTs a wallet holds in a portfolio view. For metadata on a specific NFT by contract + token ID, use `alchemy nfts metadata`.")
     .requiredOption("--body <json>", "JSON body for /assets/nfts/by-address")
     .action(async (opts: { body: string }) => {
       try {

src/commands/rpc.ts

@@ -9,7 +9,7 @@ export function registerRPC(program: Command) {
     .command("rpc")
     .argument("<method>", "JSON-RPC method name (e.g. eth_blockNumber)")
     .argument("[params...]", "Method parameters as JSON values")
-    .description("Make a raw JSON-RPC call")
+    .description("Sends a raw JSON-RPC request to an Alchemy node (e.g. eth_call, eth_getCode, eth_blockNumber). Use for low-level RPC calls only. For higher-level operations like balances, transfers, simulation, or token data, use the dedicated subcommands instead.")
     .addHelpText(
       "after",
       `

src/commands/simulate.ts

@@ -25,7 +25,7 @@ export function registerSimulate(program: Command) {
 
   cmd
     .command("asset-changes")
-    .description("Call alchemy_simulateAssetChanges")
+    .description("Simulates a transaction and returns a human-readable breakdown of asset changes (token transfers, ETH movements, NFT transfers) before it is broadcast. Use to preview what a transaction will do. For raw JSON-RPC calls, use `alchemy rpc` instead.")
     .requiredOption("--tx <json>", "Transaction object JSON")
     .option("--block-tag <tag>", "Block tag (default latest)", "latest")
     .action(async (opts: { tx: string; blockTag: string }) => {

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("Get transfer history (alchemy_getAssetTransfers)")
+    .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.")
     .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 configured wallet")
+    .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`.")
     .action(() => {
       try {
         const key = resolveWalletKey(program);

src/commands/webhooks.ts

@@ -30,7 +30,7 @@ export function registerWebhooks(program: Command) {
 
   cmd
     .command("list")
-    .description("List team webhooks")
+    .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.")
     .action(async () => {
       try {
         const token = resolveWebhookApiKey(cmd.opts());
@@ -46,7 +46,7 @@ export function registerWebhooks(program: Command) {
 
   cmd
     .command("create")
-    .description("Create webhook")
+    .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`.")
     .requiredOption("--body <json>", "Create webhook JSON payload")
     .option("--dry-run", "Preview without executing")
     .action(async (opts: { body: string; dryRun?: boolean }) => {