Enrich command and flag descriptions for AI agent consumption

Merge the detailed flag descriptions from PR #15 (max lengths, type format
hints, behavioral details, category explanations) with the examples and
Long descriptions from the search_by_contract work. Every Short, Long,
and flag help string is now maximally descriptive so AI agents can
select the right commands and flags without ambiguity.

Author: ivpusic

cli/root.go

@@ -24,9 +24,18 @@ var apiKeyFlag string
 
 var rootCmd = &cobra.Command{
 	Use:   "dune",
-	Short: "Dune CLI — interact with the Dune Analytics API",
-	Long: "A command-line interface for interacting with the Dune Analytics API.\n" +
-		"Manage queries, execute DuneSQL queries, search datasets, browse documentation, and monitor usage.",
+	Short: "Dune CLI — query, explore, and manage blockchain data on Dune Analytics",
+	Long: "A command-line interface for the Dune Analytics platform.\n\n" +
+		"Discover datasets across the Dune catalog, execute SQL queries (DuneSQL dialect),\n" +
+		"retrieve execution results, and manage your saved queries — all from the terminal.\n\n" +
+		"Capabilities:\n" +
+		"  - Search datasets by keyword, contract address, category, or blockchain\n" +
+		"  - Create, update, archive, and retrieve saved DuneSQL queries\n" +
+		"  - Execute saved queries or raw DuneSQL and display results\n" +
+		"  - Browse Dune documentation for DuneSQL syntax, API references, and guides\n" +
+		"  - Monitor credit usage, storage consumption, and billing periods\n\n" +
+		"Authenticate with an API key via --api-key, the DUNE_API_KEY environment variable,\n" +
+		"or by running `dune auth`.",
 	PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
 		if cmd.Annotations["skipAuth"] == "true" {
 			return nil

cmd/dataset/search.go

@@ -13,31 +13,37 @@ import (
 func newSearchCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "search",
-		Short: "Search for datasets across the Dune catalog",
-		Long: "Search for datasets across the Dune catalog by keyword, category, blockchain, and more.\n\n" +
-			"The catalog includes canonical blockchain data, decoded contract tables,\n" +
-			"Spellbook transformations, and community datasets. Use --include-schema\n" +
-			"to get column names and types for SQL generation.\n\n" +
+		Short: "Search for tables and datasets across the Dune catalog",
+		Long: "Natural-language table discovery across the Dune catalog. Use this command\n" +
+			"to find concrete table names for use in SQL queries.\n\n" +
+			"The catalog includes:\n" +
+			"  - canonical: chain-native primitives (blocks, transactions, logs, traces)\n" +
+			"  - decoded: ABI-level events and function calls parsed from contract interactions\n" +
+			"  - spell: curated Spellbook transformation datasets (e.g. dex.trades)\n" +
+			"  - community: user-contributed tables and uploads\n\n" +
+			"Filter by category, blockchain, schema, dataset type, or ownership scope.\n" +
+			"Use --include-schema to get column names and types for SQL generation.\n\n" +
+			"For contract-specific lookup, use 'dune dataset search-by-contract' instead.\n\n" +
 			"Examples:\n" +
 			"  dune dataset search --query \"uniswap swaps\"\n" +
 			"  dune dataset search --query \"transfers\" --categories decoded --blockchains ethereum\n" +
 			"  dune dataset search --query \"dex trades\" --categories spell --include-schema --output json\n" +
-			"  dune dataset search --owner-scope me",
+			"  dune dataset search --query \"*\" --owner-scope me",
 		RunE: runSearch,
 	}
 
-	cmd.Flags().String("query", "", "search query text")
-	cmd.Flags().StringArray("categories", nil, "filter by category (canonical, decoded, spell, community)")
-	cmd.Flags().StringArray("blockchains", nil, "filter by blockchain")
+	cmd.Flags().String("query", "", "natural-language search intent or entity hints (e.g. 'uniswap v3 swaps'); use '*' to browse without keyword bias")
+	cmd.Flags().StringArray("categories", nil, "filter by table family: canonical (chain primitives), decoded (ABI-level events/calls), spell (curated datasets), community (user-contributed)")
+	cmd.Flags().StringArray("blockchains", nil, "chain scope to reduce ambiguity and improve ranking (e.g. ethereum, solana, arbitrum)")
 	cmd.Flags().StringArray("dataset-types", nil,
-		"filter by dataset type (dune_table, decoded_table, spell, uploaded_table, transformation_table, transformation_view)")
-	cmd.Flags().StringArray("schemas", nil, "filter by schema")
-	cmd.Flags().String("owner-scope", "", "ownership filter (all, me, team)")
-	cmd.Flags().Bool("include-private", false, "include private datasets")
-	cmd.Flags().Bool("include-schema", false, "include column schema in results")
-	cmd.Flags().Bool("include-metadata", false, "include metadata in results")
-	cmd.Flags().Int32("limit", 20, "maximum number of results")
-	cmd.Flags().Int32("offset", 0, "pagination offset")
+		"fine-grained dataset type filter: dune_table, decoded_table, spell, uploaded_table, transformation_table, transformation_view")
+	cmd.Flags().StringArray("schemas", nil, "schema/namespace constraint for high precision (e.g. dex, uniswap_v3_ethereum)")
+	cmd.Flags().String("owner-scope", "", "ownership filter: all (default), me, or team; does NOT automatically include private datasets")
+	cmd.Flags().Bool("include-private", false, "widen results to include private datasets visible to the authenticated user/team alongside public ones")
+	cmd.Flags().Bool("include-schema", false, "include column-level schema (name, type, nullable) for every result; useful when preparing SQL")
+	cmd.Flags().Bool("include-metadata", false, "include category-specific metadata (page_rank_score, description, abi_type, contract_name, project_name, etc.)")
+	cmd.Flags().Int32("limit", 20, "number of results per page; use 5-15 for quick checks, 20-50 for deeper exploration")
+	cmd.Flags().Int32("offset", 0, "pagination offset; combine with limit to page through large result sets")
 	output.AddFormatFlag(cmd, "text")
 
 	return cmd

cmd/docs/search.go

@@ -14,10 +14,15 @@ const defaultMCPEndpoint = "https://docs.dune.com/mcp"
 func newSearchCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "search",
-		Short: "Search the Dune documentation",
-		Long: "Search the official Dune documentation. No authentication required.\n\n" +
-			"Look up DuneSQL syntax, API references, table naming conventions,\n" +
-			"and Dune platform concepts.\n\n" +
+		Short: "Search the Dune documentation for guides, API references, and code examples",
+		Long: "Search across all Dune documentation pages including guides, API references,\n" +
+			"DuneSQL syntax, table naming conventions, and code examples.\n" +
+			"Does not require authentication.\n\n" +
+			"Useful for looking up:\n" +
+			"  - DuneSQL functions and syntax (date/time, string, aggregate, window functions)\n" +
+			"  - API endpoint references and authentication\n" +
+			"  - Table naming conventions and dataset structure\n" +
+			"  - Dune platform concepts (decoding, Spellbook, materialized views)\n\n" +
 			"Examples:\n" +
 			"  dune docs search --query \"DuneSQL string functions\"\n" +
 			"  dune docs search --query \"execute query API\" --api-reference-only\n" +
@@ -26,7 +31,7 @@ func newSearchCmd() *cobra.Command {
 		RunE:        runSearch,
 	}
 
-	cmd.Flags().String("query", "", "search query text, e.g. 'DuneSQL date functions' or 'API authentication' (required)")
+	cmd.Flags().String("query", "", "natural-language search query for Dune docs; e.g. 'DuneSQL date functions', 'API authentication', 'decoded tables meaning', 'query pagination' (required)")
 	_ = cmd.MarkFlagRequired("query")
 	cmd.Flags().Bool("api-reference-only", false, "prioritize API reference pages over conceptual guides")
 	cmd.Flags().Bool("code-only", false, "prioritize pages with executable examples and code snippets")

cmd/execution/execution.go

@@ -7,6 +7,10 @@ func NewExecutionCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "execution",
 		Short: "Retrieve and inspect query execution results",
+		Long: "Retrieve and inspect the results of query executions.\n\n" +
+			"Use 'execution results <execution-id>' to fetch results from a previously\n" +
+			"submitted query execution. The execution ID is returned when running queries\n" +
+			"with 'dune query run --no-wait' or 'dune query run-sql --no-wait'.",
 	}
 	cmd.AddCommand(newResultsCmd())
 	return cmd

cmd/execution/results.go

@@ -17,27 +17,31 @@ var PollInterval = 2 * time.Second
 func newResultsCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "results <execution-id>",
-		Short: "Fetch results of a query execution",
-		Long: "Fetch results of a query execution by its execution ID.\n\n" +
-			"Use this after submitting a query with --no-wait, or to re-fetch results from\n" +
-			"a completed execution. The command handles all execution states:\n" +
-			"  - Completed: displays result rows\n" +
-			"  - Pending/Executing: shows current state (re-run later)\n" +
-			"  - Failed: returns the error message\n" +
-			"  - Cancelled: returns cancellation notice\n\n" +
+		Short: "Retrieve execution results for a query execution by execution ID",
+		Long: "Retrieve the results of a query execution. By default, waits for the execution\n" +
+			"to complete (up to the timeout) before returning results.\n\n" +
+			"Behavior:\n" +
+			"  1. Checks the current execution status\n" +
+			"  2. If still running: polls every 2 seconds until complete or timeout is reached\n" +
+			"  3. If completed: returns the result data\n" +
+			"  4. If failed/cancelled: returns the error details\n\n" +
+			"Use --no-wait to return the current state immediately without polling.\n" +
 			"Use --limit and --offset to paginate through large result sets.\n\n" +
+			"Use this after submitting a query with --no-wait, or to re-fetch results from\n" +
+			"a completed execution.\n\n" +
 			"Examples:\n" +
 			"  dune execution results 01JXYZ...\n" +
 			"  dune execution results 01JXYZ... --limit 100 --offset 200\n" +
+			"  dune execution results 01JXYZ... --no-wait\n" +
 			"  dune execution results 01JXYZ... --output json",
 		Args: cobra.ExactArgs(1),
 		RunE: runResults,
 	}
 
-	cmd.Flags().Int("limit", 0, "maximum number of result rows to return (0 = all)")
-	cmd.Flags().Int("offset", 0, "number of rows to skip before returning results, used for pagination")
-	cmd.Flags().Bool("no-wait", false, "return the current execution state immediately without waiting for completion")
-	cmd.Flags().Int("timeout", 300, "maximum seconds to wait for the execution to complete before timing out")
+	cmd.Flags().Int("limit", 0, "maximum number of result rows to return (0 = all); use with --offset to paginate large result sets")
+	cmd.Flags().Int("offset", 0, "number of rows to skip before starting to return results; use with --limit for pagination through large result sets")
+	cmd.Flags().Bool("no-wait", false, "return the current execution state immediately without waiting for completion; useful for checking status of long-running queries")
+	cmd.Flags().Int("timeout", 300, "maximum seconds to wait for the execution to complete before timing out (default 300s = 5 minutes)")
 	output.AddFormatFlag(cmd, "text")
 
 	return cmd

cmd/query/create.go

@@ -12,21 +12,26 @@ import (
 func newCreateCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
-		Short: "Create a new saved query",
-		Long: "Create a new saved DuneSQL query. Returns the numeric query ID on success.\n" +
-			"Use --temp to create a temporary query that won't appear in your saved queries list.\n\n" +
+		Short: "Create a new saved Dune query and return the query ID",
+		Long: "Create a new SQL query on Dune. Returns the query ID on success.\n\n" +
+			"The query is written in DuneSQL dialect. If the query targets tables with\n" +
+			"known partition columns, include a WHERE filter on those columns\n" +
+			"(e.g. WHERE block_date >= CURRENT_DATE - INTERVAL '7' DAY) to enable\n" +
+			"partition pruning and reduce query cost.\n\n" +
+			"Use --temp to create a temporary query that won't appear in the dune.com\n" +
+			"library or be accessible when shared. Temporary queries are auto-deleted.\n\n" +
 			"Examples:\n" +
 			"  dune query create --name \"Recent Blocks\" --sql \"SELECT * FROM ethereum.blocks LIMIT 10\"\n" +
 			"  dune query create --name \"My Query\" --sql \"SELECT 1\" --private --description \"Test query\"\n" +
 			"  dune query create --name \"Throwaway\" --sql \"SELECT 1\" --temp",
 		RunE: runCreate,
 	}
 
-	cmd.Flags().String("name", "", "query name (required)")
-	cmd.Flags().String("sql", "", "DuneSQL query text (required)")
-	cmd.Flags().String("description", "", "query description")
-	cmd.Flags().Bool("private", false, "make the query private")
-	cmd.Flags().Bool("temp", false, "create a temporary query (auto-deleted, not shown in your saved queries)")
+	cmd.Flags().String("name", "", "human-readable query title, max 600 characters (required)")
+	cmd.Flags().String("sql", "", "the SQL query text in DuneSQL dialect, max 500,000 characters (required)")
+	cmd.Flags().String("description", "", "short description of what the query does, max 1,000 characters")
+	cmd.Flags().Bool("private", false, "make the query private; may be forced by team privacy settings")
+	cmd.Flags().Bool("temp", false, "create a temporary query that won't appear in the dune.com library or be accessible when shared; auto-deleted")
 	_ = cmd.MarkFlagRequired("name")
 	_ = cmd.MarkFlagRequired("sql")
 	output.AddFormatFlag(cmd, "text")

cmd/query/query.go

@@ -6,10 +6,15 @@ import "github.com/spf13/cobra"
 func NewQueryCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "query",
-		Short: "Manage Dune queries",
+		Short: "Create, retrieve, update, execute, and archive Dune queries",
 		Long: "Create, retrieve, update, archive, and execute DuneSQL queries.\n\n" +
-			"Use 'query create' to save a reusable query, 'query run' to execute a saved query,\n" +
-			"or 'query run-sql' to execute raw DuneSQL without saving.",
+			"Subcommands:\n" +
+			"  create   - Save a new reusable DuneSQL query and get its query ID\n" +
+			"  get      - Fetch a saved query's SQL, metadata, and execution state\n" +
+			"  update   - Modify a query's SQL, title, description, privacy, or tags\n" +
+			"  archive  - Hide a query from the library (still retrievable by ID)\n" +
+			"  run      - Execute a saved query by ID and display results\n" +
+			"  run-sql  - Execute raw DuneSQL inline without saving a query",
 	}
 	cmd.AddCommand(newCreateCmd())
 	cmd.AddCommand(newGetCmd())

cmd/query/run.go

@@ -13,24 +13,31 @@ import (
 func newRunCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run <query-id>",
-		Short: "Execute a saved query and display results",
-		Long: "Execute a saved DuneSQL query by its numeric ID and display results.\n\n" +
-			"By default, polls every 5 seconds for up to ~5 minutes waiting for completion.\n" +
-			"Use --no-wait to submit the execution and exit immediately; then fetch\n" +
-			"results later with 'dune execution results <execution-id>'.\n\n" +
+		Short: "Execute a saved Dune query by its ID and display results",
+		Long: "Execute a saved Dune query by its numeric ID. By default, waits for the\n" +
+			"execution to complete (polling every 2 seconds) and displays the result rows.\n" +
+			"Use --no-wait to submit the execution and exit immediately with just the\n" +
+			"execution ID; then fetch results later with 'dune execution results <execution-id>'.\n\n" +
+			"Credits are consumed based on actual compute resources used. Use --performance\n" +
+			"to select the engine size (medium or large).\n\n" +
+			"Important: if the query targets tables with known partition columns (returned by\n" +
+			"'dune dataset search' or 'dune dataset search-by-contract'), ensure the SQL includes\n" +
+			"a WHERE filter on those partition columns (e.g. WHERE block_date >= CURRENT_DATE -\n" +
+			"INTERVAL '7' DAY). This enables partition pruning and significantly reduces query cost.\n\n" +
 			"Examples:\n" +
 			"  dune query run 12345\n" +
 			"  dune query run 12345 --param wallet=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --param days=30\n" +
 			"  dune query run 12345 --performance large --limit 100\n" +
-			"  dune query run 12345 --no-wait",
+			"  dune query run 12345 --no-wait\n" +
+			"  dune query run 12345 --timeout 600",
 		Args: cobra.ExactArgs(1),
 		RunE: runRun,
 	}
 
-	cmd.Flags().StringArray("param", nil, "query parameter in key=value format (repeatable)")
-	cmd.Flags().String("performance", "medium", `performance tier: "medium" (default) or "large" for higher compute resources`)
-	cmd.Flags().Int("limit", 0, "maximum number of rows to display (0 = all)")
-	cmd.Flags().Bool("no-wait", false, "submit execution and exit without waiting for results")
+	cmd.Flags().StringArray("param", nil, "typed query parameter in key=value format (repeatable); supported types: text, number (stringified, e.g. '30'), datetime (YYYY-MM-DD HH:mm:ss), enum")
+	cmd.Flags().String("performance", "medium", `engine size for the execution: "medium" (default) or "large"; credits are consumed based on actual compute resources used`)
+	cmd.Flags().Int("limit", 0, "maximum number of result rows to return (0 = all available rows)")
+	cmd.Flags().Bool("no-wait", false, "submit the execution and exit immediately, printing only the execution ID and state")
 	cmd.Flags().Int("timeout", 300, "maximum seconds to wait for the execution to complete before timing out")
 	output.AddFormatFlag(cmd, "text")
 

cmd/query/run_sql.go

@@ -10,25 +10,31 @@ import (
 func newRunSQLCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run-sql",
-		Short: "Execute raw DuneSQL and display results",
-		Long: "Execute a DuneSQL query directly without creating a saved query.\n" +
-			"Ideal for ad-hoc exploration and one-off analysis.\n\n" +
-			"By default, polls every 5 seconds for up to ~5 minutes waiting for completion.\n" +
-			"Use --no-wait to submit and exit immediately.\n\n" +
+		Short: "Execute a raw DuneSQL query inline and display results",
+		Long: "Execute an inline SQL statement in DuneSQL dialect without saving it as a\n" +
+			"query on Dune. Ideal for ad-hoc exploration and one-off analysis.\n\n" +
+			"By default, waits for completion (polling every 2 seconds) and displays result rows.\n" +
+			"Use --no-wait to submit the execution and exit immediately with just the\n" +
+			"execution ID. Credits are consumed based on actual compute resources used.\n\n" +
+			"Important: if the SQL targets tables with known partition columns (returned by\n" +
+			"'dune dataset search' or 'dune dataset search-by-contract'), include a WHERE filter\n" +
+			"on those partition columns (e.g. WHERE block_date >= CURRENT_DATE - INTERVAL '7' DAY).\n" +
+			"This enables partition pruning and significantly reduces query cost.\n\n" +
 			"Examples:\n" +
 			"  dune query run-sql --sql \"SELECT block_number, block_time FROM ethereum.blocks ORDER BY block_number DESC LIMIT 5\"\n" +
 			"  dune query run-sql --sql \"SELECT * FROM ethereum.transactions WHERE block_number = {{block_num}}\" --param block_num=20000000\n" +
-			"  dune query run-sql --sql \"SELECT COUNT(*) FROM ethereum.transactions\" --performance large",
+			"  dune query run-sql --sql \"SELECT COUNT(*) FROM ethereum.transactions\" --performance large\n" +
+			"  dune query run-sql --sql \"SELECT 1\" --no-wait",
 		Args: cobra.NoArgs,
 		RunE: runRunSQL,
 	}
 
-	cmd.Flags().String("sql", "", "DuneSQL query to execute (required)")
+	cmd.Flags().String("sql", "", "the SQL query text in DuneSQL dialect (required)")
 	_ = cmd.MarkFlagRequired("sql")
-	cmd.Flags().StringArray("param", nil, "query parameter in key=value format (repeatable)")
-	cmd.Flags().String("performance", "medium", `performance tier: "medium" (default) or "large" for higher compute resources`)
-	cmd.Flags().Int("limit", 0, "maximum number of rows to display (0 = all)")
-	cmd.Flags().Bool("no-wait", false, "submit execution and exit without waiting for results")
+	cmd.Flags().StringArray("param", nil, "typed query parameter in key=value format (repeatable); supported types: text, number (stringified, e.g. '30'), datetime (YYYY-MM-DD HH:mm:ss), enum")
+	cmd.Flags().String("performance", "medium", `engine size for the execution: "medium" (default) or "large"; credits are consumed based on actual compute resources used`)
+	cmd.Flags().Int("limit", 0, "maximum number of result rows to return (0 = all available rows)")
+	cmd.Flags().Bool("no-wait", false, "submit the execution and exit immediately, printing only the execution ID and state")
 	cmd.Flags().Int("timeout", 300, "maximum seconds to wait for the execution to complete before timing out")
 	output.AddFormatFlag(cmd, "text")