getAgentTools: caching changes

[peteski22]

Summary

Optimize agent tools caching strategy.

Refactored caching behavior for better performance:

• #agentTools() now fetches and caches ALL functions from ALL healthy servers once
• getAgentTools() filters cached results by servers and tools parameters
• Subsequent calls with different filter combinations reuse the cache without re-fetching
• refreshCache: true option forces cache regeneration when schemas change

Benefits:

• Eliminates redundant API calls when requesting different tool/server combinations
• Complete cache populated on first call enables efficient filtering
• More intuitive behavior: cache once, filter many times

Summary by CodeRabbit

Release Notes

• New Features

  • Added explicit cache refresh control via new refreshCache option in getAgentTools method
  • Tools can now be returned in multiple formats: arrays, objects, or maps
  • New public method to retrieve currently cached tools

• Documentation

  • Updated examples demonstrating new cache refresh option and output format options
  • Clarified caching behaviour and performance optimisation details

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The pull request extends getAgentTools with a refreshCache?: boolean option to enable explicit cache refresh, refactors internal tool fetching to implement caching with support for multiple return formats (array, object, map), and replaces type definitions with discriminated union types to enforce format-specific options. Unit tests verify caching behaviour.

Changes

Cohort / File(s)	Summary
Documentation & Examples README.md	Updated comments and examples to show the new refreshCache option; clarified caching semantics for generated functions and refresh mechanisms.
Core API & Caching Implementation src/client.ts, src/functionBuilder.ts	Refactored getAgentTools() public API with three overloads supporting array, object, and map formats; implemented internal caching in #agentTools() with refresh support; introduced getCachedFunctions() method in FunctionBuilder; added single-line error message formatting.
Type System Updates src/index.ts, src/types.ts	Replaced ToolFormat with AgentToolsFormat; introduced discriminated union types (ArrayAgentToolsOptions, ObjectAgentToolsOptions, MapAgentToolsOptions) extending BaseAgentToolsOptions with refreshCache?: boolean property; updated exports to reflect new type structure.
Test Suite Enhancements tests/unit/client.test.ts	Added centralised fetch mock configuration; introduced new test suite verifying cache reuse, selective refetching with refreshCache: true, and correct filtering by servers and tools with caching.

Possibly related PRs

• Add tool name filtering to getAgentTools() #17: Modifies getAgentTools API with client-side tool filtering (tools?: string[]), whereas this PR centralises post-fetch server and tool filtering.

Suggested reviewers

• khaledosman

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and specifically summarizes the main change: introducing caching optimizations to the getAgentTools method.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch peteski22/agent-tools-caching

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d7796d9 and 259c6f6.

⛔ Files ignored due to path filters (1)

• examples/langchain/package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (6)

• README.md (3 hunks)
• src/client.ts (8 hunks)
• src/functionBuilder.ts (1 hunks)
• src/index.ts (1 hunks)
• src/types.ts (1 hunks)
• tests/unit/client.test.ts (3 hunks)

🧰 Additional context used

🧬 Code graph analysis (3)

tests/unit/client.test.ts (2)

tests/unit/utils/mockApi.ts (1)

• createFetchMock (30-63)

src/apiPaths.ts (1)

• API_PATHS (10-44)

src/types.ts (1)

src/index.ts (6)

• AgentToolsFormat (47-47)
• BaseAgentToolsOptions (48-48)
• ArrayAgentToolsOptions (49-49)
• ObjectAgentToolsOptions (50-50)
• MapAgentToolsOptions (51-51)
• AgentToolsOptions (52-52)

src/client.ts (2)

src/functionBuilder.ts (1)

• AgentFunction (21-44)

src/types.ts (4)

• ArrayAgentToolsOptions (320-322)
• ObjectAgentToolsOptions (328-330)
• MapAgentToolsOptions (336-338)
• AgentToolsOptions (344-347)

🔇 Additional comments (8)

src/functionBuilder.ts (1)

407-415: Cache accessor is straightforward and safe

getCachedFunctions() returns a snapshot array of cached functions without exposing the underlying Map, which fits the intended use in McpdClient.#agentTools() and keeps cache mutation controlled by FunctionBuilder.

src/index.ts (1)

47-51: Type re-exports align with new getAgentTools API

Re-exporting the new agent tools option/format types keeps the public surface in sync with src/types.ts and McpdClient.getAgentTools overloads; this looks correct.

README.md (1)

464-466: Caching and refreshCache documentation matches implementation

The IMPORTANT note, options comment, and refreshCache: true example all correctly describe that functions are cached once and later calls reuse the cache irrespective of filters, with explicit override via refreshCache or clearAgentToolsCache(). This is consistent with McpdClient.getAgentTools()’ current behaviour.

Also applies to: 478-480, 564-566

tests/unit/client.test.ts (3)

506-547: Combined server+tool filtering test uses shared mock cleanly

Stubbing fetch with createFetchMock for this test and constructing a fresh McpdClient instance makes the server+tool filter expectations explicit and decoupled from the outer beforeEach mock; this looks solid.

---

827-979: Caching behaviour tests accurately exercise new semantics

The new "getAgentTools caching behavior" tests verify the key scenarios:

• First call populates the cache and subsequent calls reuse it (asserted via fetchCallCount).
• Different combinations of servers and tools filters are served from cache without extra fetches.
• refreshCache: true causes additional fetches and repopulation.

The use of createFetchMock keeps fixtures focused on API paths and tools, and the local client instances avoid interference with the top-level client/mockFetch. This suite gives good coverage of the new caching contract.

---

1124-1147: Logging fixture correctly triggers “non-existent server” path

Configuring API_PATHS.SERVERS to include "nonexistent" while omitting it from HEALTH_ALL simulates a server missing from the health map and correctly exercises the "Skipping non-existent server 'nonexistent'" warning path; the test and fixture are coherent.

src/types.ts (1)

275-347: Agent tools option types are well-structured and match overloads

The introduction of AgentToolsFormat, BaseAgentToolsOptions, and the discriminated union (ArrayAgentToolsOptions, ObjectAgentToolsOptions, MapAgentToolsOptions) gives getAgentTools a clear, type-safe surface and lines up with the overloads in McpdClient. The refreshCache documentation also correctly describes its intent.

src/client.ts (1)

77-93: Internal aliases for agent tool collection types improve clarity

AgentFunctionsArray, AgentFunctionsRecord, and AgentFunctionsMap give readable names to the three internal collection shapes used by the formatters and keep the implementation of getAgentTools tidy without affecting the public API.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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