Clarity — 113 Operations for AI Agents

This page is the canonical reference an AI coding agent uses to refactor, query, and analyze Clarity code through the act MCP server. 113 operations available: 68 refactor, 15 query, 30 analysis. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.

15Query

68Refactor

30Analysis

Query

Operation	Description
`callers`	Find every call site of a function or method across the codebase. Use to understand who depends on a function before changing its signature. Requires LSP. Params: symbol (string) [, file (string)]
`control_flow`	Get a function's control flow — branches, loops, early returns, and basic blocks in execution order. Use to understand complex logic without reading the full implementation. Params: target (string), file (string)
`definition`	Jump to definition — find where a symbol is defined given a usage location. Uses abstract syntax trees by default, no LSP required. Params: symbol (string), file (string), line (u32), column (u32)
`diagnostics`	Get compiler errors and warnings from the language server. Omit `file` for workspace-wide diagnostics. Pass a file path or directory path to scope results. Requires LSP.
`fix_auto`	Auto-fix all deterministic issues in a file, directory, or workspace — missing imports, unused imports, simple type errors. Runs multiple fix-revalidate cycles. Use after making changes to clean up automatically. Requires LSP. Params: none [, file (string), workspace_mode (bool), category (string), commit (bool), max_rounds (u32)]
`get_type`	Get the compiler-inferred type of any expression at a position. Use to understand types without reading surrounding code. Requires LSP. Params: file (string), line (u32), column (u32)
`graph`	Build a dependency graph from a file — trace what it imports and what imports it, across multiple hops. Use to understand module relationships and change impact before refactoring. Params: file (string) [, depth (u32), direction (string), leaves (bool), order (string)]
`import_organize`	Organize, sort, and deduplicate imports in a file. Removes unused imports. Use after adding new code or moving symbols to clean up import blocks automatically. Params: file (string) [, preview (bool)]
`interface`	Get a symbol's public API — signatures, types, and docstrings without implementation bodies. Like skeleton but for a single symbol. Use to understand how to call something without reading its internals. Params: target (string), file (string) [, include_private (bool)]
`mutations`	Identify side effects — what external state a function reads or writes (globals, file I/O, network, etc.). Use to understand if a function is pure or has hidden dependencies. Params: target (string), file (string)
`references`	Find every usage of a symbol across the entire codebase — all files, not just the current one. Use before renaming, refactoring, or deleting to understand full impact. Requires LSP. Params: symbol (string), file (string)
`repo_outline`	Get a compressed overview of the entire repository in one call — file tree with languages, line counts, and optionally symbol names per file. Orders of magnitude cheaper than listing directories and reading files individually. Params: none [, path (string), depth (u32), include (glob), exclude (glob), symbols (bool), max_files (u32), relative (bool)]
`skeleton`	Get a file's structure — function signatures, class declarations, type definitions — without implementation bodies. Use INSTEAD of reading the full file to understand its API. Typically 5-10x fewer tokens than reading the raw file. Params: file (string)
`symbols`	List all symbols (functions, classes, variables, types, constants) defined in a file with their locations and kinds. Use INSTEAD of reading a file when you need to know what's defined in it. Much cheaper than reading the full file. IMPORTANT: file must be a path to a single source file — never a directory or empty string. Params: file (string)
`symbols_batch`	Retrieve symbols from multiple files in a single call. Use instead of calling symbols() in a loop — one request instead of N. Params: none [, files (string[]), ids (string[]), kinds (string[])] — provide files or ids

Refactor

Operation	Description
`add-contract-caller-check`	Add contract-caller authorization guard
`add-overflow-check`	Add overflow guard before arithmetic
`add-parameter-to-private-function`	Add parameter to private function
`add-principal-check`	Add tx-sender authorization guard
`add-response-check`	Wrap call in (try! ...) for error propagation
`add-stx-transfer-guard`	Add balance check before STX transfer
`convert-err-value-to-response`	Wrap value in (err ...) for response type
`convert-if-to-match`	Convert if to match for response/optional
`convert-integer-to-uint`	Convert signed int to unsigned uint
`convert-is-ok-to-match`	Convert is-ok check to match
`convert-is-some-to-match`	Convert is-some check to match
`convert-match-to-if`	Convert match to if when simple
`convert-ok-unwrap-to-try`	Replace unwrap! pattern with try! macro
`convert-ok-value-to-response`	Wrap value in (ok ...) for response type
`convert-string-to-ascii`	Convert string-utf8 literal to string-ascii
`convert-unwrap-err-panic-to-match`	Replace unwrap-err-panic with match
`convert-unwrap-panic-to-unwrap`	Replace unwrap-panic with unwrap!
`demote-to-private-function`	Change public function to private
`extract-access-control-guard`	Extract repeated asserts into private function
`extract-constant`	Extract literal into named constant
`extract-filter-predicate`	Extract filter predicate into function
`extract-let-binding`	Extract an expression into a let binding
`extract-private-function`	Extract code block into private function
`extract-read-only-function`	Extract pure code into read-only function
`extract_function`	Extract a code selection into a new function — automatically infers parameters, return types, and inserts the call site. Use instead of manually cutting/pasting code. Works without LSP; LSP improves type inference. Params: file (string), new_name (string), start_line (u32), start_column (u32), end_line (u32), end_column (u32) [, preview (bool)]
`extract_variable`	Extract an expression into a named variable — inserts the declaration and replaces the expression with the variable name. Works without LSP. Params: file (string), new_name (string), start_line (u32), start_column (u32), end_line (u32), end_column (u32) [, preview (bool)]
`generate-access-control-map`	Generate access control map with helpers
`generate-clarity-doc-comment`	Generate documentation comment
`generate-contract-call-wrapper`	Generate contract-call wrapper function
`generate-define-constant`	Generate define-constant declaration
`generate-define-data-var`	Generate define-data-var declaration
`generate-define-fungible-token`	Generate define-fungible-token declaration
`generate-define-map`	Generate define-map declaration
`generate-define-non-fungible-token`	Generate define-non-fungible-token declaration
`generate-define-private-stub`	Generate private function stub
`generate-define-public-stub`	Generate public function stub
`generate-define-read-only-stub`	Generate read-only function stub
`generate-error-constants`	Generate block of error constant definitions
`generate-ft-mint-public`	Generate public FT mint function
`generate-ft-token-scaffold`	Generate full SIP-010 FT token scaffold
`generate-impl-trait`	Generate impl-trait declaration
`generate-nft-collection-scaffold`	Generate full SIP-009 NFT collection scaffold
`generate-nft-mint-public`	Generate public NFT mint function
`generate-owner-only-guard`	Generate owner constant and guard function
`generate-sip009-get-owner`	Generate SIP-009 get-owner function
`generate-sip009-transfer`	Generate SIP-009 transfer function
`generate-sip010-get-balance`	Generate SIP-010 get-balance function
`generate-sip010-get-total-supply`	Generate SIP-010 get-total-supply function
`generate-sip010-transfer`	Generate SIP-010 transfer function
`generate-stx-transfer-public`	Generate public STX transfer function
`generate-trait-definition`	Generate trait definition skeleton
`generate-use-trait`	Generate use-trait import
`inline`	Inline a variable, function, or method — replace every usage with its definition body, then remove the original. The inverse of extract. Works without LSP (single-file); LSP enables cross-file inlining. Params: file (string), symbol (string) [, line (u32), preview (bool)]
`inline-constant`	Replace constant with its value
`inline-let-binding`	Inline a let binding into all uses
`insert_body`	Replace a function's implementation body with new code. AST-validated — rejects if the result has parse errors, so you can't accidentally break syntax. Use instead of manual text editing for function rewrites. Params: file (string), symbol (string), code (string) [, commit (bool)]
`invert-boolean-condition`	Negate if condition and swap branches
`move_symbol`	Move a function, class, or type to a different file and automatically update all imports across the codebase. Use instead of manually cut/paste + fixing imports. Works without LSP (single-file); LSP enables cross-file import updates. Params: file (string), symbol (string), destination (string) [, preview (bool)]
`normalize-error-constants`	Replace inline error literals with named constants
`promote-to-public-function`	Change private function to public
`rename`	Rename a symbol and automatically update ALL references across the codebase. Safer and faster than find-and-replace — AST-aware, won't rename strings or comments. Works without LSP (single-file); LSP enables cross-file renames. Params: file (string), old_name (string), new_name (string) [, line (u32), column (u32), preview (bool)]
`rename-identifier`	Rename an identifier across all references
`rename-map-key-tuple-field`	Rename field in map tuple definition and usages
`reorder-function-parameters`	Reorder parameters of a function
`rewrite-fold-as-map`	Convert fold to map when appropriate
`rewrite-map-as-fold`	Convert map to fold when needed
`simplify-boolean-expression`	Simplify boolean expressions (double negation, constants)
`unwrap-option-to-default`	Replace default-to with direct expression

Analysis

Operation	Description
`analyze_chokepoints`	Find files that act as critical bottlenecks — high betweenness centrality in the dependency graph (R4). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_clusters`	Identify tightly coupled groups of files using community detection. Use to discover natural module boundaries and understand which files change together. Params: none [, granularity (string), min_size (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_cohesion`	Measure intra-module cohesion for each file — ratio of internal to total symbol edges (H2). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_coupling`	Measure coupling per file — how many files depend on it (afferent) vs how many it depends on (efferent), plus instability and abstractness scores. Use to find the most critical/fragile files. Params: none [, granularity (string), sort (string), threshold (f64), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_cycle_risk`	Score each circular dependency cycle by its external risk surface (R6 circular risk zones analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_cycles`	Find circular dependency chains in the codebase. Use to identify import cycles that cause build issues or indicate architecture problems. Params: none [, granularity (string), max_length (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_dead_code`	Find dead code — functions, classes, and types that are never referenced from any entry point. Use before cleanup to safely identify what can be deleted. Params: none [, entry (string[]), granularity (string), include_tests (bool), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_depth`	Compute longest transitive dependency chain per file (S4 dependency depth analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_entry_points`	Detect entry points: main functions, HTTP routes, CLI commands, event listeners, test files (S5). Params: none [, include (string[]), exclude (string[])].
`analyze_export`	Export the full semantic graph (files, symbols, dependencies) in JSON, DOT (Graphviz), or CSV format. Use for visualization or external analysis. Params: none [, format (string), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_extraction`	Score clusters for service or package extraction viability (M2 extraction candidates analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_fan_balance`	Compute fan-in/fan-out imbalance for migration ordering guidance (M6 fan balance analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_features`	Inventory language-specific AST features used in the codebase — async, generics, decorators, etc. (M3). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_hotspots`	Rank files by composite complexity score — max cyclomatic complexity, statement count, nesting depth (H1). Params: none [, top_n (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_impact`	Compute change impact for a target file — finds all files directly and transitively depending on it (R1). Params: target (string) [, max_depth (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_inconsistencies`	Detect inconsistent abstractions — sibling files in the same directory that diverge from the group's structural pattern (H5). Params: none [, include (string[]), exclude (string[])].
`analyze_inheritance`	Detect tangled inheritance — deep hierarchies (>N levels) and diamond inheritance (H6). Params: none [, include (string[]), exclude (string[])].
`analyze_interface_bloat`	Detect interface bloat — files where the public API is disproportionately large relative to implementation (H3). Params: none [, include (string[]), exclude (string[])].
`analyze_interfaces`	Map cross-module interfaces — symbols that cross directory-module boundaries, ranked by interface width (M4). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_layers`	Detect architectural layers from directory names and find dependency direction violations (S1+S2). Params: none [, detect_only (bool), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_orphan_types`	Find type definitions used exclusively outside their defining directory (H4 orphan types analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_patterns`	Find code smells — god functions, deep nesting, high coupling, and other structural issues. Use to identify refactoring targets or assess code quality. Params: none [, tier (string), pattern (string), file (string), severity (string), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_platform_deps`	Detect platform-specific API usage by scanning imports (M5 platform dependencies analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_readiness`	Compute migration readiness scores per file — composite of complexity, coupling, porting blockers (M1). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_roles`	Classify files by architectural role: entry point, routing, business logic, data access, config, test, utility, types, generated (S3). Params: none [, include (string[]), exclude (string[])].
`analyze_seams`	Find the natural boundaries between file clusters — the narrowest points where groups of files communicate. Use to identify where to split modules or add API boundaries. Params: none [, min_cluster_size (u32), max_seam_width (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_stability`	Compute stability index (R2) and detect stable dependency violations (R3) — flags edges where stable modules depend on unstable ones. Params: none [, index_only (bool), include (string[]), exclude (string[])].
`analyze_surface`	Measure API surface area — count exposed functions, types, and complexity at a module boundary. Use to assess whether an API is too large or leaky. Params: none [, boundary (string), files (string), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_test_gaps`	Detect source files with no or partial test coverage based on graph import analysis (R5). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=["crates"], exclude=["corpus"]).
`analyze_type_completeness`	Analyze type boundary completeness — detect 'any' types, untyped parameters, missing return types at exported function boundaries (M7). Params: none [, include (string[]), exclude (string[])].

← CircomClojure →