deephaven-mcp: Skill for Claude Code

Single source of truth. The canonical, exact-match wording for the "Terminology Note" and "Format Accuracy for AI Agents" sections lives in mcp-tool-sections.md. Other skills reference that file rather than duplicating the wording — duplicates drift. Load it when a tool docstring needs those sections.

Review the docstrings in the specified file for correctness, completeness, and clarity. Also review the module-level docstring at the top of the file. Only change docstrings — do not change source code.

Only make a change if there is a significant improvement. Unnecessary changes make code review harder.

Correctness: Apply the pydocs-accuracy criteria — description, Args, Returns, Raises must all match the actual code; no stale documented behavior.

Type information: Function signatures must have type annotations, and docstrings must also document types in Google style:

• Args: param (type): description
• Returns: type: description
• Raises: ExceptionType: description

Completeness: Every non-trivial function and class should have a docstring. Args, Returns, and Raises sections should be present when applicable.

Pydantic fields: Every field on a StrictSchema / RedactableSchema subclass needs runtime-introspectable documentation. Apply the ref-configuration-conventions skill for the canonical rule and examples; in summary:

• Each field carries a PEP 257 trailing docstring (triple-quoted string immediately below the assignment line). The project enables use_attribute_docstrings=True on the base so Pydantic harvests it into model_fields[name].description.
• Sphinx Attributes: blocks on the class docstring are invisible to model_json_schema() and the MCP tool surface — remove any redundant Attributes: listing when adding trailing docstrings.
• Explicit Field(description="...") works at runtime but violates project style — convert to the trailing-docstring form opportunistically.
• Verify with uv run python -c "from <module> import <Model>; print(<Model>.model_fields['<field>'].description)"; None or an empty string means the field is undocumented at runtime regardless of what the class docstring says.
• Enforced by tests/test_field_docs_contract.py.

Contract, not context: A docstring documents what the function accepts, returns, and raises — not its surrounding context. Specifically, do not include:

• A list of callers (it's grep-recoverable and creates maintenance friction when callers change)
• Per-caller behavioral exposition (each caller's reason for using the function belongs in that caller's docstring or in a design comment, not here)
• Future-evolution hedging like "current rules", "at present, only...", or "additional rules can be added" (the docstring describes what the function does today; future changes are documented when they happen)
• Implementation rationale beyond what a caller needs to use the function correctly (rationale belongs in commit messages, design docs, or inline comments at the implementation site)
• Another type's internal structure — its sub-fields, its members, or its validation mechanics. Name the type and stop; that type's own docstrings own those details. Applies to module, class, and field docstrings alike.

If a docstring describes the world outside the function — its callers, its design history, its future plans, or the internals of a type it merely references — it's wrong. This holds for module and class docstrings with the same force.

# WRONG — re-narrates AuthConfig's internals; duplicates the Schema::
# block and AuthConfig's own field docstrings, and drifts when either changes
"""... the `auth` block validates to `AuthConfig`, whose `credentials`
is a `CredentialsUnion` at `auth.credentials` ..."""

# RIGHT — name the type and stop
"""... the `auth` block (an `AuthConfig`) carries the connection credentials ..."""

Module and package docstrings: A package __init__.py docstring is a one-line statement of what the package is, plus a list of its surface submodules — nothing more. The "Contract, not context" rule applies with the same force here; module/package docstrings are the most common place it is violated. Specifically: