read
readRead 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
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes | The entity to read, or 'catalog' to list what you can read. | |
| filters | No | Entity-specific filters (see read('catalog')). An organization id is never a filter. | |
| options | No | Paging + projection. |