Toolset overview

This vignette explains why each rairai tool exists and which AI-agent workflows it supports. Use it together with the numbered design principles in vignettes/design.qmd when deciding whether a tool is useful, redundant, or better expressed as part of a higher-level workflow.

Target workflows

The toolset should be judged against common workflows where an AI agent benefits from R-specific structure and evidence.

W1 — Understand a symbol

Answer: what is this object, where is it defined, and where is it used? Useful tools should resolve a name to candidates, return a definition location, list references, and make ambiguity explicit.

W2 — Prepare a safe code change

Before editing, an agent should find the relevant object, inspect the source range with its normal file-reading tools, understand affected call sites, and find related tests and exported API status.

W3 — Refactor without guessing

For renaming, moving, or restructuring code, an agent needs a map of definitions, references, exported names, namespace declarations, and tests. rairai should prefer previewable evidence over tools that silently mutate code.

W4 — Diagnose a failure or warning

When tests or checks fail, an agent needs to connect messages to source locations and package context. Tools should help inspect the relevant object, references, dependencies, documentation, and namespace state.

W5 — Explore an unfamiliar package

An agent joining a codebase needs quick orientation: package files, dependencies, namespace exports/imports, file-scoped symbols, and important symbols. This should not require reading every source file in full.

W6 — Add or update tests

When changing behavior, an agent needs to find the implementation, related tests, and call sites. Tools should identify objects and affected files, while ordinary file and shell tools handle reading, editing, and running tests.

Tool surface and package roots

serve() is the only exported R function. It exposes 21 public MCP tools that accept names, paths, scopes, and package concepts. Calls in this guide use MCP argument notation, not exported R functions.

The 19 package-local tools use the immutable canonical default selected by serve(path = ...). To inspect another directory, repeat its native absolute package_root on every applicable call. Omitted, NULL, or empty selectors use the default; relative paths, tilde paths, and file URIs are not root selectors. The directory must exist and is canonicalized, including symlink resolution. Resolved responses report the effective root in package_root. The CRAN tools cran_search and cran_package have no root selector.

path and context_path filter within the effective root; they do not select a package. package retains each tool’s installed-documentation, external-function, or imported-package meaning. In particular, package_docs() defaults to local documentation, while help_search() without package searches local and installed help. External function signatures remain unsupported by function_formals(); use the help tools instead.

Roots are unrestricted process-readable directories. File listings and package-role readers can disclose more than conventional package metadata, and responses disclose canonical absolute host paths. Within-package containment is not a race-free sandbox; process or container permissions provide strong filesystem confinement.

Usability goals

Design tool names, descriptions, and outputs so that an agent is nudged toward a small number of obvious first moves:

Avoid exposing multiple tools that appear to answer the same question unless the difference changes the agent’s next action. If a distinction mainly reflects an implementation backend, keep it private.

Where useful, responses should include compact routing hints such as counts, ambiguity status, returned path/range fields, and suggested lower-level tools to call next. These hints should be structured fields rather than prose summaries so agents can act on them reliably.

Tool purposes

This section describes the toolset from the perspective of an AI coding agent. Tools are grouped by the task they help an agent perform, not by the underlying data source used to implement them.

Package orientation tools

Use these tools when the agent needs to understand the package shape before choosing files or symbols to inspect. They provide R-package context that ordinary file readers and text search do not reconstruct reliably.

Preferred workflow routes

Symbol and source navigation tools

Use symbols() to find code entities or decide what source range to read next. Package source indexing covers flat R/*.[Rr] files.

Definition, reference, and impact tools

Function inspection tools

Use this tool when the agent needs to call or modify a function without loading the target package.

Test and documentation discovery tools

R6 structure tools

Questions for tool review

When reviewing the toolset, ask:

  1. Which workflows does this tool support?
  2. Which design principles justify its shape?
  3. Is it a preferred LLM-facing tool, a lower-level primitive, or redundant?
  4. Would a combined workflow tool reduce repeated calls without hiding ambiguity?
  5. Does the tool provide R-package or R-language intelligence that ordinary file/search/shell tools do not already provide?
  6. Are optional arguments robust if an MCP client fills in NULL, an empty string, a schema default, or the first enum value instead of omitting them?