Skip to main content
Glama

Sergio by Serviche

read

read
Read-only

Read ANYTHING about the business: read(entity, filters). ENTITIES (key: purpose [main filters]): conversations: The inbox list of conversations [status, from, to, needs_reply, conversation_id, ...] | conversation_transcript: A client's whole history in one timeline [conversation_id, client_ref, from, to, search] | communications: Every text, email and call across the business in ONE read [from, to, direction, channel, contact_type, ...] | calls: Call log [conversation_id, client_ref, from, to, direction, ...] | bookings: Bookings by status/date/client/cleaner [status, frequency, from, to, date_axis, ...] | booking_time_logs: Cleaner clock-in/out records as a SET read [from, to, staff, client_ref, booking_id, ...] | booking_notes: Tiered booking notes + the flat booking note [booking_id] | clients: Look up contacts by id [id, name, name_words, phone, email, ...] | contact_groups: The business's live Contacts tags and lists, as the Contacts page's side nav shows them [kind] | client_standing: Visit count + last visit per client, with the client name [client_ref, client_ids] | client_case_file: Full context for a client's thread [conversation_id, client_ref, question, as_of] | owner_directives: Standing asks the owner gave the team in the team channel [status, from, to] | tasks: Tasks [status, task_id, client_ref, conversation_id, flow, ...] | cockpit_queue: The Sergio cockpit / Needs-Attention queue | activity_log: Audit trail of changes [days, from, to, search, actor, ...] | scheduling_decisions: The scheduling decision log [booking_id, days] | chat_turns: Each Sergio chat turn's AI cost and time, newest first, read from the AI usage log [turn_id, days] | staff_roster: The cleaner/staff roster, counted in code | staff_detail: Detail for one staff member [staff, kind, from, to] | staff_events: Every logged staff event org-wide [from, to, kind, staff, sentiment, ...] | client_checkins: Every client check-in / feedback record org-wide [from, to, client_ref, staff, outcome, ...] | google_reviews: The business's Google reviews as Sergio stores them [match_status, from, to, client_ref, stars, ...] | staff_signals: Clustered staff signals/feedback over a window [days] | staff_scheduling_rules: Per-staff scheduling rules/availability constraints | sops: The business's handbook [search, slug, id, audience] | sop_versions: Versions of ONE handbook article [sop_id] | sop_questions: Questions the team asked that the handbook did not answer [status] | training_modules: Training modules [status, module_id] | training_assignments: Who is assigned which training module, with status and deadline [module_id] | company_documents: SOP files the business uploaded, with the Flows and recurring tasks Sergio suggested... | findings: Product gaps / bugs filed on the /development board | financial_reports: Org-wide money rollups [from, to] | lead_pursuits: The Leads ledger [from, to, active, owed_by, task_status, ...] | campaigns: The Growth campaigns list [status, campaign] | campaign_recipients: Who each campaign reached [campaign, state, client_ref, from, to, ...] | flows: The business's flows as the Automations page lists them [flow, active] | scanners: The business's Scanners as the Scanners page lists them [scanner, enabled] | import_jobs: Imports as the Imports page and Data sources list them [status, source] | conversation_flows: Each time a flow or program [flow, status, outcome, client_ref, from, ...] | settings: Every setting of this business, from the one settings registry [area]. read('catalog') gives each entity's full description, every filter and field, and which this caller may read. E.g. read("bookings",{status:"cancelled"}), read("conversation_transcript",{client_ref:"Maria Lopez"}), read("cockpit_queue"), read("settings",{area:"ai"}) to learn which model powers you and where to switch it. A client_ref is a FULL name or an id (a bare first name may need disambiguation. Answer a needs_disambiguation result by re-reading with the candidate's id). from/to dates are the business's local calendar days. A value-set filter (each entity's setFilters in read('catalog'): status, state, outcome…) takes one value, a list (["completed","scheduled"] or "completed,scheduled"), a negation ("!cancelled"), or exclude_ (e.g. exclude_status:"cancelled"); an unknown value is an error naming the valid ones. A ref filter (each entity's refFilters in read('catalog'): client_ref, staff) takes one ref, a JSON array of refs (matches any; a single string is always ONE ref, commas included), "!ref" or exclude_ to drop, up to 25 refs per read; a ref in the set that matches no one or several people returns that ref's no_match / needs_disambiguation. SEVERAL AT ONCE: conversations (conversation_id or client_ref, up to 10); conversation_transcript (conversation_id or client_ref, up to 10); client_case_file (conversation_id or client_ref, up to 5); staff_detail (staff, up to 10) take a list of values and answer every one in ONE call (items[] in the order asked); never loop one read per person. Everything is org-scoped and read-only; you never pass an organization id. List reads carry returned/total/truncated: when truncated is true you saw only the most recent returned of total (or of more). Say so plainly and narrow with filters (a date range from/to, a status, a client). TO RETRIEVE A SET COMPLETELY: if truncated, page with options.limit = N (up to 100) and options.offset = 0, N, 2N … until returned < N or offset >= total. Pages are stable (ties break on id), so paging never repeats or skips a row. A group_by read pages its GROUPS the same way: groups_total says how many exist and next_offset (with paging_hint) is the options.offset of the next page. TO COUNT ("how many X", "bookings per status"): read with the filter and use total. Issue one filtered read per value and read each total; NEVER eyeball or tally a capped page of rows.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "entity": "<entity>"
    },
    "name": "read"
  }
}

Input Schema

NameRequiredDescriptionDefault
entityYesThe entity to read, or 'catalog' to list what you can read.
filtersNoEntity-specific filters (see read('catalog')). An organization id is never a filter.
optionsNoPaging + projection.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / filters / properties / task_id
      Added value: +{
      +  "description": "Filter for: tasks."
      +}
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantial context beyond them: org scoping with no organization id, truncation flags (returned/total/truncated), stable id-tiebreak paging, group_by group paging via next_offset, no_match/needs_disambiguation outcomes, and errors naming valid values for unknown filter values.

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 content is operational and largely earns its place, but it is delivered as one sprawling paragraph with a long entity catalog that duplicates the schema enum and a dense tail of filtering, paging, and counting rules. It is front-loaded with the core signature, yet scannability suffers and some schema-duplicated material could be trimmed.

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

Completeness5/5

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

For a single mega-tool spanning 41 entities with no output schema, the description covers the critical decision points: scoping, filter syntax, multi-entity batching, disambiguation, truncation disclosure, deterministic paging, nested-list paging, and counting methodology. An agent has enough information to invoke it correctly without guessing.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds meaning the schema lacks: value-set filters accept a single value, a list, a negation, or exclude_<key>; ref filters accept up to 25 refs and treat a comma-containing string as one ref; from/to are the business's local calendar days; and several entities accept lists of conversation_id/client_ref/staff values answered in one call.

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 opens with a specific verb and resource ('Read ANYTHING about the business: read(entity, filters)') and then enumerates every readable entity with its purpose and main filters. An agent can tell exactly what this tool does and how it differs from mutating siblings without opening the schema.

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 detailed operational guidance: value-set and ref filter semantics, batching several refs into one call ('never loop one read per person'), when to use read('catalog') for full filter/field descriptions, and how to count via `total`. It does not explicitly position itself against close siblings such as `query` or the standalone `catalog` tool, which keeps it from a 5.

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.

Resources