Skip to main content
Glama

btlabs Core

by dev.btlabs
OverviewDiscussionsAdmin

findTestimonials

Customer quotes for use in testimonials-block. author + quote required. Optional headline = one-line key statement shown above the quote — verbatim from the quote or approved by the customer, never invented. Rating 1-5. featured: true makes it prominent. rating = stars shown on THIS quote only; the site never derives an overall rating from quotes (no JSON-LD, no brand.json rating). Has drafts: use _status:"published" to go live (draft stays hidden); schedule a future date via the schedulePost tool (collection "testimonials"). testimonials collection. Drafts: yes (publish workflow; a find WITHOUT draft:true returns the published main-table state only). Public read: yes via /api/agents. MCP capabilities: find, create, update, delete. ⚠ delete is PERMANENT (hard-delete; the admin Trash does NOT catch MCP deletes). Before writing public text here, call getWritingGuidelines with this collection and the locale (brand voice, writing rules, fixed terms, SEO rules, taken keywords, field rules). Fields: author (required), role (localized), company, avatar (upload: media|brand), headline (localized), quote (textarea, localized, required), rating (number, 1–5), featured (boolean), publishedAt (date).

Input Schema

NameRequiredDescriptionDefault
idNoOptional: specific document ID to retrieve. If not provided, returns all documents
pageNoPage number for pagination (default: 1)
sortNoField to sort by (e.g., "createdAt", "-updatedAt" for descending)
depthNoHow many levels deep to populate relationships (default: 0)
draftNoOptional: Whether the document should be queried from the versions table/collection or not.
limitNoMaximum number of documents to return (default: 10, max: 100)
whereNoOptional JSON string for where clause filtering (e.g., '{"title": {"contains": "test"}}')
localeNoOptional: locale code to retrieve data in (e.g., "en", "es"). Use "all" to retrieve all locales for localized fields
selectNoOptional: define exactly which fields you'd like to return in the response (JSON), e.g., '{"title": true}'
fallbackLocaleNoOptional: fallback locale code to use when requested locale is not available

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the burden well: it discloses draft behavior, that a find without `draft:true` returns only the published main-table state, public read access via `/api/agents`, and the permanent nature of deletes. It does not describe read-side pagination or authentication details, but the core behavioral traits are covered.

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

Conciseness3/5

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

The description is front-loaded and organized, but it is long and includes write/delete and field-requirement details that are not directly needed to invoke a find tool. Those details serve the collection documentation but reduce focus for this specific operation.

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?

Given no annotations and no output schema, the description supplies useful collection context: fields, required/localized semantics, draft workflow, public read behavior, and writing-guideline routing. It stops short of describing the find response envelope or pagination metadata, but it is largely complete for selecting and calling this query tool.

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

Parameters3/5

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

The input schema already documents all 10 query parameters at 100% coverage, so the baseline is 3. The description adds some meaning around the `draft` parameter and `_status` filtering, but it does not meaningfully explain the other query parameters beyond what the schema provides.

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

Purpose4/5

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

The description identifies the resource clearly as customer quotes in the testimonials collection for testimonials-block use, which distinguishes it from sibling find* tools for other collections. It is not quite a crisp verb-first statement, and it also lists create/update/delete capabilities, which slightly muddies whether this tool itself is only for finding.

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

Usage Guidelines4/5

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

It gives clear usage context for testimonials-block, explains the published/draft behavior, says to use `_status:"published"` to go live, and routes scheduling to `schedulePost`. It does not explicitly name alternatives or exclusions among sibling find* tools, so it falls short of a 5.

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

All btlabs Core toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources