docs(iorails): Tool calling docs

[tgasser-nv]

Description

Add tool-calling page to Guardrail docs explaining at a high-level how tool-calling works over multiple inferences and the harness execution, where IORails' new tool calls fit into this flow. Includes configuration details on how to set it up.

Page is under Configure Guardrails / Guardrail Catalog / Tool Calling.
Direct link is: https://nvidia-preview-pr-2099.docs.buildwithfern.com/nemo/guardrails/configure-guardrails/guardrail-catalog/tool-calling

Related Issue(s)

This docs PR stacks on top of the last PR in the stack below:

• feat(iorails): Tool-calling - non-streaming tool calling to main LLM #2016
• feat(iorails): Tool-calling - streaming tools from main LLM #2024
• feat(iorails): Add tool-calling rails to RailsManager and ModelRegistry #2030
• feat(iorails): Connect tool-calling up in IORails #2058

Verification

$ make docs-fern-strict
FERN_VERSION=$(node -p "require('./fern/fern.config.json').version") && cd fern && npx --yes "fern-api@${FERN_VERSION}" docs md
 generate --library guardrails-python-sdk
Library 'guardrails-python-sdk': generated 285 pages at /Users/tgasser/projects/nemo_guardrails_worktree/docs/iorails-tool-call
ing-docs/docs/_static/python-sdk-reference
✓ Generated library documentation for 1 libraries
                                             ╭──────────────────────────────────╮
                                             │                                  │
                                             │        Upgrades available        │
                                             │                                  │
                                             │      Fern 5.50.5 → 5.56.3        │
                                             │   (Run fern upgrade to update)   │
                                             │                                  │
                                             ╰──────────────────────────────────╯

node scripts/normalize-fern-sdk-reference.mjs
Moved 0 generated package overview pages to index.mdx.
Removed 0 duplicate package overview pages with existing index.mdx.
FERN_VERSION=$(node -p "require('./fern/fern.config.json').version") && cd fern && npx --yes "fern-api@${FERN_VERSION}" check
All checks passed

AI Assistance

• No AI tools were used.
• AI tools were used; a human reviewed and can explain every change (tool: ___).

Checklist

• I've read the CONTRIBUTING guidelines.
• This PR links to a triaged issue assigned to me.
• My PR title follows the project commit convention.
• I've updated the documentation if applicable.
• I've added tests if applicable.
• I've noted any verification beyond CI and any checks I couldn't run.
• I did not update generated changelog files manually.
• I addressed all CodeRabbit, Greptile, and other review comments, or replied with why no change is needed.
• @mentions of the person or team responsible for reviewing proposed changes.

Summary by CodeRabbit

• New Features
  • Added a new Guardrail Catalog page for tool calling, including guidance on validating tool calls and tool results.
  • Expanded the Rails configuration reference with clearer setup notes and behavior details for tool-related validation.
  • Added navigation links so the new tool calling documentation is easier to find.

[github-actions]

Staged Fern docs preview: https://nvidia-preview-pr-2099.docs.buildwithfern.com/nemo/guardrails

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new tool-calling.mdx guardrail catalog page documenting IORails tool-calling rails, including validation rules, engine enablement, configuration, streaming behavior, and limitations. Updates the configuration reference to describe IORails-specific tool rail semantics, and registers the new page in the navigation index and catalog.

Changes

IORails Tool-Calling Rails Documentation

Layer / File(s)	Summary
Navigation and catalog card registration docs/index.yml, docs/configure-rails/guardrail-catalog/index.mdx	Inserts a "Tool Calling" entry into the navigation tree and adds the matching catalog card linking to the new page.
Configuration reference: tool rails rewrite docs/configure-rails/configuration-reference.mdx	Replaces the generic tool rails description with IORails-specific flow names (tool call validation, tool result validation), documents the single-name constraint per section, and notes that parallel is accepted but not honored.
New tool-calling catalog page docs/configure-rails/guardrail-catalog/tool-calling.mdx	New page covering the full feature: bidirectional validation flow, pipeline position, IORails engine enablement, config.yml setup, tool declaration (per-request and static), tool call and tool result validation rules, per-request toggles, streaming behavior, and limitations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• NVIDIA-NeMo/Guardrails#1892: Updates documentation for enabling IORails via the Guardrails(..., use_iorails=True) entry point, the same enablement pattern described in the new tool-calling page.
• NVIDIA-NeMo/Guardrails#2058: Implements the IORails tool-calling rails with tool call validation / tool result validation flow semantics that this PR documents.

Suggested reviewers

• cparisien
• Pouyanpi
• miyoungc

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding IORails tool-calling documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Results For Major Changes	✅ Passed	Docs-only change; PR description includes verification output from make docs-fern-strict with all checks passed.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/iorails-tool-calling-docs

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR adds a new Tool Calling page to the Guardrails Catalog documenting the IORails engine's tool-calling rails (tool call validation and tool result validation), and updates the configuration reference with accurate IORails-specific descriptions and consistent YAML formatting.

• New tool-calling.mdx covers the complete function-calling loop, how IORails rails slot into the pipeline, configuration, per-request control, streaming behavior, and limitations — including a complete end-to-end code example addressing prior review feedback.
• configuration-reference.mdx reformats all YAML examples to 4-space indentation and aligned table columns, and replaces the generic placeholder flow names in the Tool Rails section with the actual IORails flow names plus a cross-reference link.

Confidence Score: 5/5

Documentation-only change with no runtime impact; safe to merge.

All changes are documentation: a new reference page, nav wiring, a catalog index entry, and reformatting of the configuration reference. The new page is accurate, the external OpenAI link resolves correctly, prior review comments have been fully addressed, and no code paths are touched.

No files require special attention.

Important Files Changed

Filename	Overview
docs/configure-rails/guardrail-catalog/tool-calling.mdx	New documentation page for IORails tool-calling rails; covers the multi-step function-calling loop, how rails fit the pipeline, configuration, declaration of tools, per-request control, streaming, and limitations — all accurately and with complete end-to-end code examples.
docs/configure-rails/configuration-reference.mdx	Reformats YAML examples from 2-space to 4-space indentation and aligns table columns throughout; also updates the Tool Rails section with accurate IORails-specific flow names and a cross-reference to the new tool-calling page.
docs/configure-rails/guardrail-catalog/index.mdx	Adds a Tool Calling card linking to the new page; also fixes the hyphenation of 'third-party' in the page description.
docs/index.yml	Inserts the Tool Calling page into the navigation after Agentic Security with the correct path and slug.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant App as Application
    participant GR as IORails
    participant LLM as Model

    App->>GR: 1. Request with tool definitions
    GR->>LLM: Forward request
    LLM-->>GR: 2. Tool calls (model output)
    Note over GR: tool call validation<br/>(rails.tool_output)
    GR-->>App: Validated tool calls
    App->>App: 3. Execute the function
    App->>GR: 4. Request with tool results
    Note over GR: tool result validation<br/>(rails.tool_input)
    GR->>LLM: Forward request
    LLM-->>GR: 5. Final response or more tool calls
    GR-->>App: Final response

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant App as Application
    participant GR as IORails
    participant LLM as Model

    App->>GR: 1. Request with tool definitions
    GR->>LLM: Forward request
    LLM-->>GR: 2. Tool calls (model output)
    Note over GR: tool call validation<br/>(rails.tool_output)
    GR-->>App: Validated tool calls
    App->>App: 3. Execute the function
    App->>GR: 4. Request with tool results
    Note over GR: tool result validation<br/>(rails.tool_input)
    GR->>LLM: Forward request
    LLM-->>GR: 5. Final response or more tool calls
    GR-->>App: Final response

Loading

_{Reviews (4): Last reviewed commit: "Merge branch 'develop' of github.com:NVI..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/configure-rails/guardrail-catalog/tool-calling.mdx`:
- Around line 300-305: Update the “Related tool features” section in the
tool-calling MDX so the product name reads “the NVIDIA NeMo Guardrails library”
and the two internal links use the rendered Fern routes from docs/index.yml
instead of the source-style paths. Adjust the “Tools Integration” and “Rail
types” references in this section accordingly, keeping the rest of the copy
unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d3c55651-4ab1-4f87-a318-19fa02adc9e4

📥 Commits

Reviewing files that changed from the base of the PR and between 3e94bdd and 33002c0.

📒 Files selected for processing (4)

• docs/configure-rails/configuration-reference.mdx
• docs/configure-rails/guardrail-catalog/index.mdx
• docs/configure-rails/guardrail-catalog/tool-calling.mdx
• docs/index.yml