MCP tool descriptions

Source and stability

src/server/presentation.rs composes named prose sections; src/server/arguments.rs owns the input schema. The canonical handshake records the advertised definition.

Presentation comes from captured configuration, not completed background discovery. It stays stable when startup succeeds or fails. Configured languages control visible code fields and relevant examples; actual runtime availability is checked during execution. Python dependency guidance follows the captured existing/managed selection and managed resolution policy, including launch-time RETICULATE_PYTHON when no Python selection is configured. Existing environments use installed packages; managed environments describe explicit declarations, automatic import preparation, or fixed startup requirements as selected. Under explicit resolution, hiding requirements.python or its parent switches generated Python guidance to installed packages. Configuration exports leave generated Python parameter descriptions as null so later launches regenerate them after selection; explicit description overrides are preserved. Requirements can remain visible for a hidden SQL provider.

Launcher tool configuration applies after generated presentation. It can replace tool prose, initialization instructions, and nested parameter descriptions verbatim, or hide parameters while preserving their omission defaults. The editorial guidance below governs generated text; explicit replacements are owned by the launcher.

Do not equate visibility with initialization, installation, or a security boundary. Bridge examples require both source languages to be visible; Python-owned SQL registration must not imply that an R-owned connection is a DB-API object.

Deferred tool discovery

MCP initialization instructions introduce the server; the send definition explains the tool. Start both with a short task-oriented summary so deferred-discovery clients can choose Console before loading its full schema.

These are separate protocol fields: initialize returns server instructions; tools/list returns each tool’s description and inputSchema, including argument descriptions. Initialization makes instructions available to the client before it lists tools. The client decides which text to put in the model’s context and when. Fetching a definition from Console does not necessarily expose that definition to the model immediately.

With deferred loading, a server summary can help the model decide where to search before it receives individual tool schemas. Claude Code’s server-author guidance describes using initialization instructions for that decision. Other integrations can use a separately supplied server description, as in the Responses API tool-search workflow. Instructions are therefore relevant beyond the connection handshake, but their visibility is client-dependent. The R console_tool() adapter uses the tool description and schema to construct its ellmer tool; it does not automatically add initialization instructions to the chat prompt.

The implementation review recorded on October 9, 2026 found a 250-character first-line preview in the examined Codex deferred-discovery implementation and a documented default 2,048-character cap in Claude Code. These are dated client behaviors, not MCP limits. See the pinned Codex preview implementation and Claude Code author guidance.

Use those sizes as practical editorial targets, not guarantees that every client exposes all of the text. Recheck client behavior when revising discovery guidance. Detailed budget allocation and client feature flags do not belong in Console’s public contract.

Editorial rules

Lead with tasks: calculations, data analysis, simulations, debugging, queries, plots, and comparing approaches with retained state. Follow with complete-cell and automatic-display guidance.

Language-selection guidance encourages choosing a language for each step, including continuing in R after Python and combining R expressions with Python calls through reticulate. When R, Python, and SQL are exposed, use:

Choose whichever language makes each step easiest to express, even when earlier steps used another language. Switch between R, Python, and SQL cells, reusing results through the language bridges, or use reticulate within an R cell to combine R expressions with Python objects and function calls. For example, read a specialized format with a Python library, then continue with an R data frame to transform or summarize the data, fit a statistical model, or make a plot.

The R/Python interface uses the same paragraph with SQL omitted from the list. Other interfaces with multiple languages retain the first sentence; single-language interfaces omit switching guidance. Custom workers describe switching through their own capabilities without promising the built-in language bridges. The paragraph replaces the separate R/Python/SQL selection advice when both R and Python are exposed. Reusable R script instructions belong in the R parameter description.

When SQL is exposed, follow with a short reminder of DuckDB’s file and database access:

DuckDB can query CSV, Parquet, JSON/JSONL file globs, and databases via extensions.

The SQL field illustrates reading file sets as tables, including nested fields, with read_json('data/*.json*'). Keep the result-retrieval helpers and connection ownership rules in the language fields.

Give each fact one primary home:

Preserve defaults in prose where missing schema-default rendering would be misleading. Keep the empty-send polling rule and discourage repeated one-second polls. Preserve warnings that errors do not roll back effects and restart discards live state.

Ordinary use should not require declaration inspection, preparation, language switching, or restart. Do not turn the description into a package list, protocol guide, or help API. Response notices own current state, missing prerequisites, and omitted-output locations.

Do not remove a capability’s only usable explanation in favor of a repository link: the agent may not have the checkout. Exact helper names and essential restrictions must remain available in the tool definition.

Capability and security claims

Describe configured capabilities without claiming that dependencies are already installed. An advertised language can fail because the runtime is unavailable; advertising it does not authorize installation. Preparation guidance must reflect the selected runtime and resolution policy.

Policy text must reflect selected native permissions. Name the configured temporary and workspace write grants and concrete writable paths, subject to narrower read/deny rules. Metadata protection is a default, not a mandatory ceiling. A read entry grants reads as well as narrowing writes.

Do not imply that resolver settings and worker settings are the same boundary, or that a declaration is an installed-package inventory. Keep supported interrupt-plus-cell partial effects explicit.

Comparing the advertised definition

Capture the canonical handshake and affected configuration/platform companions before editing. Regenerate through:

scripts/test --update client_server/server/test_tools::initializes_and_lists_tools

Then run the focused case without updating. Compare the top-level description, all nested descriptions, and the complete tool object. Remove description fields recursively and require unchanged remaining schema/metadata for a prose-only edit. Argument order may change without changing schema values.

Use the same compact serialization and tokenizer for comparisons; report UTF-8 bytes alongside token counts. Smaller text alone does not demonstrate better agent behavior. TODO records the evaluation work; do not claim a wording improvement is measured without an evaluation.