Guide: Tuning Your Cashmere MCP Server

Once your MCP server is connected and returning results, fine-tuning it for your specific application dramatically improves agent reliability, reduces token consumption, and gives you precise control over what the agent can and cannot do.

All of the options described here are configurable in the Cashmere Console — no code changes required.

Prerequisite: A working MCP server. If you haven't set one up yet, start with Setting Up Your First MCP Server with a Content License.

---

Overview

There are four main levers:

1. Enable only the tools your application needs — controls what the agent can call
2. Hide input parameters the agent shouldn't use — narrows the agent's input surface per tool
3. Hide response fields you don't need — reduces token usage and context noise
4. Customize tool descriptions — shapes when and how the agent invokes each tool

All four are configured per MCP server in the Console under MCP Servers → [your server] → Edit → Tools.

---

Common Workflows

1 — Enable Only the Tools Your Application Needs

Every tool the agent sees is a decision it has to make on every request. Unused tools add context overhead and increase the chance of unexpected invocations. Only enable the tools your application's workflow actually requires.

Tool reference — when to enable and when to leave off:

search_publications

Semantic + text search across licensed content. Returns ranked content snippets with source metadata.

Enable when: your application answers questions, surfaces relevant passages, or powers a RAG pipeline. This is the core tool for the majority of applications.

Leave off when: your application only browses the library structure and never performs free-text search.

---

list_publications

Returns all publications available under the license, with metadata like title, creators, and cover image.

Enable when: you want the agent to orient itself before searching — knowing which titles are available helps it answer source-scoped questions more accurately. Also useful for browsing and discovery UIs.

Leave off when: your application always searches without needing to enumerate titles first, or the library is large enough that listing it upfront would consume too many tokens.

---

get_publication

Returns full metadata and navigation structure for a single publication, identified by UUID.

Enable when: your application needs to inspect a specific publication's structure, chapter list, or detailed metadata before drilling in. Typically used alongside get_table_of_contents.

Leave off when: your application doesn't need per-publication detail — most search-only applications don't need this.

---

list_collections

Returns all collections available under the license.

Enable when: your application lets users browse or select from content collections, or when you want the agent to understand the content organization before searching.

Leave off when: your application always searches across all licensed content and doesn't need collection-level navigation.

---

get_collection

Returns details for a single collection, identified by ID.

Enable when: you need the agent to confirm what's inside a specific collection before scoping a search to it.

Leave off when: you don't use collection-scoped filtering, or list_collections is sufficient.

---

get_usage_report_summary

Returns token consumption and usage data, optionally filtered by date, API key, or external ID.

Enable when: your application surfaces consumption data to the user or to an admin dashboard, or when you need the agent to answer questions about usage.

Leave off when: usage reporting is handled externally or by a human. Most end-user applications should leave this off — exposing it risks the agent invoking it unnecessarily on unrelated queries.

---

find_relevant_sources (Deep Research)

Searches across licensed content and returns one result per unique source document — the best-matching excerpt per publication, with a section_block_uuid you can pass directly to get_section.

Enable when: your application supports deep research workflows where the agent needs to identify which publications are most relevant before reading them in depth. Use this as the entry point for multi-step research instead of search_publications.

Leave off when: your application only needs snippet-level search results and doesn't do deep-read workflows.

---

get_table_of_contents (Deep Research)

Returns the full navigation structure of a publication — section labels, ordering, and section_block_uuid for each section.

Enable when: your application needs to navigate a publication's structure explicitly, or when the agent needs to browse sections not surfaced by find_relevant_sources.

Leave off when: you always jump to sections via section_block_uuid from find_relevant_sources and don't need full TOC navigation.

---

get_section (Deep Research)

Returns the full text of a specific section, paginated. Accepts a section_block_uuid (from find_relevant_sources) or a section_order (from get_table_of_contents).

Enable when: your application needs to read full section content — not just snippets. This is the deep-read tool and is the final step in a research workflow.

Leave off when: snippet-level results from search_publications are sufficient. get_section consumes tokens proportional to section length, so only enable it if your application genuinely needs full-text access.

---

Recommended configurations by application type:

Application type	Recommended tools
RAG / Q&A	search_publications
RAG with library context	search_publications, list_publications
Deep research agent	find_relevant_sources, get_table_of_contents, get_section
Content browser / discovery	list_publications, list_collections, get_collection
Full research platform	All tools

---

2 — Hide Input Parameters the Agent Shouldn't Use

Each tool exposes a set of input parameters. Parameters the agent doesn't need add noise to its context and can produce unexpected behavior — for example, an agent that sees a collection_id filter may try to use it even when you want it to search across all licensed content.

Hideable parameters by tool:

search_publications

• external_ids — comma-separated tracking IDs attached to the search for usage reporting. Hide if your application doesn't use per-user or per-session tracking. Keep if you need to reconcile Cashmere usage against your own analytics.
• omnipub_uuids — filter results to specific publication UUIDs. Hide if the agent should always search across the full licensed library. Keep if your application scopes searches to individual titles.
• collection_id — filter results to a specific collection. Hide if the agent should search across all licensed content. Keep if your application is scoped to a single collection.
• published_after / published_before — date filters. Hidden by default. Only expose if your application has a temporal dimension (e.g. news, research currency).

list_publications

• limit — caps the number of results returned. Hide to let the server use its default. Keep if your application manages pagination explicitly.
• offset — pagination offset. Same guidance as limit.
• collection_id — filter to a specific collection. Same guidance as search_publications.

list_collections

• limit, offset — same guidance as above.

get_usage_report_summary

• external_ids — filter the report to specific tracking IDs.
• api_key — filter the report to a specific API key. Hide unless the application needs key-level granularity.
• license_right — filter by license right type. Hide unless your application distinguishes between license right types.

find_relevant_sources

• collection_id — same guidance as search_publications.
• limit — caps the number of unique sources returned (default: 10). Hide to use the default. Keep if your application controls result count explicitly.
• published_after / published_before — hidden by default. Same guidance as search_publications.

get_section

• section_block_uuid — the preferred way to jump to a section (from find_relevant_sources). Keep for most deep research workflows.
• section_order — navigate by position (from get_table_of_contents). Hide if your workflow always uses section_block_uuid.
• page — pagination within long sections. Hide if your application always reads only the first page of a section.

---

3 — Hide Response Fields You Don't Need

Tool responses include many fields — metadata, relevance scores, source UUIDs, cover images, and more. Fields the agent doesn't need consume tokens and add noise to its context. Hiding them keeps responses lean and focused.

search_publications response fields:

Field	What it contains	Keep when	Hide when
content	The matched text snippet from the publication	Always — this is the core result	Never
view_source_url	A shareable URL linking to the source passage	Users need to read or cite the source	Your application only uses the snippet text
omnipub_title	The title of the publication the snippet came from	You surface source attribution	You don't show attribution
omnipub_publisher	The publisher's name	You surface publisher attribution	Not relevant to your application
omnipub_creators	List of authors/creators	You surface author attribution	Not relevant to your application
omnipub_published_at	Publication date	Your application has a temporal dimension	You don't use publication dates
section_label	The section or chapter heading the snippet came from	You show where the snippet sits in the source	Not needed for snippet-only display
score	Relevance score (float)	Development and debugging	Production — remove to reduce noise
omnipub_uuid	The publication's unique identifier	Your application chains to get_publication or get_section	You don't use other publication tools
section_block_uuid	The section's unique identifier	Your application chains to get_section	You only need the snippet
omnipub_cover_image	URL to the publication's cover image	Your UI displays cover art	Text-only applications
omnipub_external_id	Your external identifier for the publication	Your application maps back to your own catalog	Not needed for most RAG applications

list_publications response fields (per item):

Field	What it contains	Keep when	Hide when
uuid	Publication unique identifier	Always — needed for follow-on tool calls	Never
data.title	Publication title	Always	Never
data.subtitle	Subtitle	You display full bibliographic detail	Title alone is sufficient
data.creators	Authors/creators list	You surface author attribution	Not relevant
data.creation_date	Publication date	Your application has a temporal dimension	Not relevant
data.publisher	Publisher name	You surface publisher attribution	Not relevant
data.source_url	Link to the publication's source	You provide external links	Not relevant
cover_image	Cover image URL	Your UI displays cover art	Text-only applications
external_id	Your external ID for the publication	Your application maps to your own catalog	Not relevant for most applications

get_publication response fields:

Field	What it contains	Keep when	Hide when
uuid	Publication identifier	Always	Never
data.title	Title	Always	Never
data.subtitle	Subtitle	Full bibliographic display	Not needed
data.publisher	Publisher name	You surface publisher attribution	Not needed
data.creators	Authors list	You surface author attribution	Not needed
data.creation_date	Publication date	Temporal workflows	Not needed
data.cover_image	Cover image URL	Visual UI	Text-only applications
data.nav	Full table of contents structure	Deep navigation workflows	Applications using get_table_of_contents instead
data.epub_url	URL to the EPUB file	Direct file access workflows	Most applications
data.file_url	URL to the source file	Direct file access workflows	Most applications
data.source_url	External source link	You provide external links	Not needed
data.metadata	Extended publication metadata	Rich bibliographic applications	Most applications
data.content_selector	CSS selector for content rendering	Custom rendering workflows	Most applications
license_rights	List of license rights granted	Applications that vary behavior by rights type	Most RAG applications
external_id	Your external ID for the publication	Your application maps to your own catalog	Most applications

find_relevant_sources response fields:

Field	What it contains	Keep when	Hide when
omnipub_uuid	Publication identifier	Always — needed to call get_section	Never
omnipub_title	Publication title	Always — needed for attribution	Never
relevance_excerpt	The most relevant snippet from this source	Always	Never
section_block_uuid	Section identifier for direct get_section access	Your workflow chains to get_section	Not using deep read
section_label	Section/chapter heading	You show where the excerpt sits	Not needed
omnipub_publisher	Publisher name	You surface publisher attribution	Not needed
omnipub_published_at	Publication date	Temporal workflows	Not needed
score	Relevance score	Development and debugging	Production — remove to reduce noise

get_section response fields:

Field	What it contains	Keep when	Hide when
section.text	Full section text content	Always	Never
section.section_label	Section/chapter heading	You show section context	Not needed
section.section_order	Position in the publication	Navigation workflows	Not needed
section.page / section.total_pages	Pagination state	Your application manages pagination	Single-page reads
section.token_count	Token count for the section	Token budgeting / billing workflows	Most applications
omnipub_title	Publication title	Attribution	Not needed in context
view_source_url	Shareable source URL	Users need to follow or cite the source	Internal-only workflows
next / prev	Cursors to adjacent sections/pages	Your application walks through a publication	Single-section reads
total_sections	Total section count for the publication	Navigation/progress display	Not needed

---

4 — Customize Tool Descriptions

The description the agent receives for each tool determines when it invokes that tool, how it interprets the results, and how it handles edge cases. The defaults are written for general use. For a production application, rewriting them in terms of your specific content domain produces significantly more reliable behavior.

Best practices:

Replace generic language with domain-specific language. The default search_publications description reads: "Search through publications by semantic relevance." For a specialized application, this might become something like: "Search the licensed reference library for expert guidance, best practices, and in-depth analysis on [your domain]." The agent now knows exactly what kind of content to expect and when to reach for this tool.

Be explicit about when to use — and when not to use — each tool. Agents respond well to clear guidance. For example:

"Use this tool whenever the user asks a question that may be answered by the licensed content. Do not use it for questions about account settings, billing, or general knowledge that does not require licensed content."

Set expectations on result format and quality. If your content has a specific structure, tell the agent:

"Results are structured sections from authoritative reference material. Each result includes a text excerpt and a source URL. Use the excerpt as context; cite the source URL when presenting the answer to the user."

Guide multi-step chaining behavior. For deep research workflows, describe the expected sequence:

"Use find_relevant_sources first to identify which publications are most relevant to the query. Then use get_section with the returned section_block_uuid to read the full content of the most relevant section. Do not call get_section without first calling find_relevant_sources."

Scope the tool to your domain's vocabulary. Use the language your users and your content actually use:

"Search the licensed content library for information relevant to [your domain]. Best used for queries about specific topics, concepts, or guidance covered by your licensed collections."

Keep descriptions concise. Aim for 2–4 sentences per tool. Descriptions that are too long add to the agent's context on every request.

---

Search Model Selection

When creating or editing an API key, you can set a default search model. The recommended models are:

Model	Best for
vtups2r-1155 (default)	General-purpose hybrid search (BM25 + semantic, RRF fusion) — start here
vtups2n-1155	Hybrid search with norm fusion — try if RRF fusion isn't performing well for your content
knn1-1	Pure semantic / vector search — best when user queries differ significantly in wording from source text

Leave the default (vtups2r-1155) unless you have a clear reason to switch. You can also override the model per-request using the search_model parameter on /api/v2/search.

---

Further Reading

• Setting Up Your First MCP Server with a Content License
• Cashmere MCP Tools reference
• AI Search on Licensed Content
• Types of License Rights