@redpanda-data/docs-extensions-and-macros 4.12.6 → 4.13.1

package/mcp/COSTS.adoc

@@ -0,0 +1,167 @@
+= MCP Tool Costs
+:description: Cost reference for Redpanda documentation MCP server tools
+
+The typical cost range is $0.017 - $0.190 per operation.
+
+Most operations cost between $0.03 - $0.08. Content review operations range from $0.017 (simple terminology checks) to $0.19 (comprehensive generated docs reviews).
+
+== Cost factors
+
+You control costs through:
+
+* *Model selection*: Choose the appropriate model when starting Claude Code (Haiku for simple tasks, Sonnet for most work, Opus for complex reasoning)
+* *Prompt caching*: The MCP server caches style guides and frequently-used content, reducing costs for repeated operations
+* *Content size*: Larger documents and more comprehensive reviews increase costs proportionally
+
+== Cost by tool
+
+[cols="2m,4a,1a"]
+|===
+|Tool |Prompt |Cost (USD)
+
+|get_antora_structure
+|Get the Antora structure
+|0.055
+
+|get_redpanda_version
+|Get the latest Redpanda version
+|0.033
+
+|get_console_version
+|Get the latest Redpanda Console version
+|0.033
+
+|generate_property_docs
+|Generate property docs for tag v25.3.1
+|0.076
+
+|generate_metrics_docs
+|Generate metrics docs for tag v25.3.1
+|0.072
+
+|generate_rpk_docs
+|Generate RPK docs for tag v25.3.1
+|0.034
+
+|generate_rpcn_connector_docs
+|Generate Redpanda Connect connector docs
+|0.072
+
+|generate_helm_docs
+|Generate Helm docs for tag v25.1.2
+|0.052
+
+|generate_crd_docs
+|Generate CRD docs for tag operator/v25.3.1
+|0.084
+
+|generate_bundle_openapi
+|Bundle OpenAPI for tag v25.3.1
+|0.068
+
+|generate_cloud_regions
+|Generate cloud regions table
+|0.051
+
+|review_generated_docs
+|Review the autogenerated metrics docs
+|0.104 - 0.190
+
+|review_content (terminology)
+|Check terminology in a sentence
+|0.017
+
+|review_content (style)
+|Review content for style guide compliance
+|0.065
+
+|review_content (comprehensive)
+|Comprehensive content review
+|0.062
+|===
+
+== How to measure costs
+
+To track costs during testing:
+
+. Run a single MCP tool operation.
+. Use the `/cost` command to view accumulated costs.
+. Record the cost for that operation.
+. Restart Claude Code to reset costs for the next measurement.
+
+Example:
+
+[source,bash]
+----
+# In Claude Code CLI
+> Get the latest Redpanda version
+> /cost
+----
+
+The `/cost` command shows:
+
+* Total cost for the session
+* Duration (API time and wall time)
+* Code changes made
+* Usage breakdown by model (input/output tokens, cache usage)
+
+=== API time and wall time
+
+*API time (API duration)*:: The total time the Claude API spent actively processing and generating responses. This is what you're billed for.
+
+*Wall time (wall clock time)*:: The total elapsed time from start to finish of your session. This includes API processing time, network latency, time between requests, and time spent reading/thinking.
+
+For example:
+----
+Total duration (API):  52s
+Total duration (wall): 3m 31s
+----
+
+In this case:
+
+* API used 52 seconds of compute time (billable)
+* The session took 3 minutes 31 seconds total (user experience)
+* The 159-second difference includes network time, reading responses, and pauses between operations
+
+== Choosing the right model
+
+The model you use significantly affects costs. Start Claude Code with the appropriate model for your work:
+
+[source,bash]
+----
+# Haiku - Fast and cheap (best for simple tasks)
+claude --model haiku
+
+# Sonnet - Balanced (default, good for most work)
+claude --model sonnet
+
+# Opus - Most capable (use for complex reasoning)
+claude --model opus
+----
+
+=== Model recommendations by task
+
+*Use Haiku for:*
+
+* Generating documentation from structured data (properties, metrics, RPK commands)
+* Simple content reviews focused on terminology or style
+* Quick operations that don't require deep reasoning
+
+*Use Sonnet for:*
+
+* Comprehensive content reviews
+* Working on complex documentation tasks
+* Most day-to-day documentation work
+
+*Use Opus for:*
+
+* Extremely complex reasoning tasks
+* Architectural decisions about documentation structure
+* Currently not needed for most documentation tasks
+
+== Cost optimization tips
+
+* *Choose the right model*: Use Haiku for simple generation tasks, Sonnet for most work
+* *Leverage caching*: The MCP server caches style guides and prompts - repeated operations in the same session are cheaper
+* *Batch similar work*: Do multiple reviews or generations in one session to maximize cache benefits
+* *Use focused reviews*: For content review, use `focus: "terminology"` or `focus: "style"` instead of `focus: "comprehensive"` when you only need specific feedback