Skip to main content
Glama

CarlNotes

Search CarlNotes

search
Read-only

Find CarlNotes topics, podcast episodes, posts, findings, teams, and profiles by name, the same search the site's search bar and search page run. Rank by relevance, newest, or trending, and page through the results. Each result has its url on carlnotes.com. To rank one topic's findings by meaning, use search_topic_findings. Use it when the user asks Carl or CarlNotes to find something across the site, with phrases like search CarlNotes, find a topic, or look up a podcast episode.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoThe text to search for.
pageNoThe page to return, counted from 1.
sizeNoHow many results a page holds: 5, 10, 25, 50.
sortNorelevant ranks by how well the name matches, newest by date, and trending by visitors, listeners, and views.relevant
tagsNoTopic tags that narrow the results to topics and what belongs to them.
viewNoWhich findings to find: all, unread, or bookmarked. The last two read the connected account's marks and find findings alone.all
kindsNoThe kinds of results to find. All of them if left out. users finds profiles, and topicPosts finds posts.
tagMatchNoHow the tags match a topic: any of them, all of them, none of them, or off to ignore them.any
resourceKindsNoThe kinds of findings to find: read, watch, and listen. All of them if left out.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already covers the safety profile, so the description's job is to add context, which it does: it discloses the ranking modes, that results are pageable, and that each result carries a carlnotes.com url. It does not discuss result caps, empty-query behavior, or account requirements for the unread/bookmarked views (though the schema alludes to them), leaving a small gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, followed by sort/paging, the sibling disambiguation, and the usage trigger — a sensible order. It runs slightly long, and the sentence about result urls sits awkwardly between ranking and the alternative-tool pointer, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nine-parameter, no-output-schema tool, the description supplies what the annotations and schema cannot: cross-site scope, name-based matching, ranking intent, and the routing alternative. What remains thin is the interaction between q, tags, and view (e.g., whether q can be empty when filtering), which the agent must infer from parameter descriptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description adds a genuinely useful semantic constraint the schema does not: matching is by NAME rather than full text, which changes how an agent should phrase q. It also summarizes the sort triad at a high level, though it adds nothing for paging, tags, or kinds beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and enumerates the exact resource types covered (topics, podcast episodes, posts, findings, teams, profiles) and the matching basis (by name). It also states it is the same engine behind the site's search bar, which pins the semantics. That is enough for an agent to separate it from siblings like search_topic_findings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when-to-use trigger ('when the user asks Carl or CarlNotes to find something across the site') with concrete phrasings, and names the alternative for the one adjacent case (ranking a single topic's findings by meaning → search_topic_findings). Both the inclusion and the exclusion condition are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.