Skip to main content
Glama
chrischall

OurFamilyWizard MCP

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

ofw_list_messages

Retrieve cached OurFamilyWizard messages filtered by folder, date range, or topic. Auto-refresh syncs stale data so you get verified, complete results.

Instructions

List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based (1-based page) but if you know what you want (a date range, a topic), prefer the filters over walking pages — the cache may have 1000+ messages. Results are newest-first by default; sort:"oldest" starts at the old end of a range instead of paging to it. Returns an explicit complete boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" — check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qNoSubstring match on subject AND body (case-insensitive). Use to find messages on a specific topic.
pageNoPage number (default 1)
sizeNoMessages per page (default 50)
sortNoResult order: "newest" (default, newest first) or "oldest" (oldest first). This decides which end a truncated page keeps — with "newest" page 1 of a wide date range holds its most RECENT slice, with "oldest" its earliest. Use "oldest" to start at the old end of a range instead of paging to it.
viewNoResponse shape: "compact" (default) drops fields the response already carries elsewhere; "full" returns every field this server understands. compact omits OurFamilyWizard's raw `listData` echo, which duplicates this record's own id, subject, sentAt, recipients and read flag; the sender is promoted to `from`, and `files`/`replied` are kept. Pass "full" for the echo.
sinceNoISO date or datetime — only messages with sent_at >= since (inclusive)
untilNoISO date or datetime — only messages with sent_at < until (exclusive)
folderIdNoFolder name: "inbox", "sent", or "both" (default "both")
autoRefreshNoIf the result comes back EMPTY from a cache that is not verified-fresh, sync the backing folders first and answer from the refreshed cache instead of refusing. Defaults to the OFW_AUTO_REFRESH env var (false unless set), in which case the call refuses with result:"UNVERIFIED_EMPTY" and names the remedy. Costs OFW requests when it fires.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.15.1
    • addedInput schema / properties / view
      Added value: +{
+  "description": "Response shape: \"compact\" (default) drops fields the response already carries elsewhere; \"full\" returns every field this server understands. compact omits OurFamilyWizard's raw `listData` echo, which duplicates this record's own id, subject, sentAt, recipients and read flag; the sender is promoted to `from`, and `files`/`replied` are kept. Pass \"full\" for the echo.",
+  "enum": [
+    "compact",
+    "full"
+  ],
+  "type": "string"
+}
  2. Changed1 schema field changedv2.14.0
    • addedInput schema / properties / sort
      Added value: +{
+  "description": "Result order: \"newest\" (default, newest first) or \"oldest\" (oldest first). This decides which end a truncated page keeps — with \"newest\" page 1 of a wide date range holds its most RECENT slice, with \"oldest\" its earliest. Use \"oldest\" to start at the old end of a range instead of paging to it.",
+  "enum": [
+    "newest",
+    "oldest"
+  ],
+  "type": "string"
+}
  3. Changed1 schema field changedv2.9.2
    • addedInput schema / properties / autoRefresh
      Added value: +{
+  "description": "If the result comes back EMPTY from a cache that is not verified-fresh, sync the backing folders first and answer from the refreshed cache instead of refusing. Defaults to the OFW_AUTO_REFRESH env var (false unless set), in which case the call refuses with result:\"UNVERIFIED_EMPTY\" and names the remedy. Costs OFW requests when it fires.",
+  "type": "boolean"
+}
  4. First observedv2.8.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only include readOnlyHint=false, so the description carries the behavioral burden, and it delivers richly: result ordering, inclusive vs exclusive date semantics, the `complete` boolean's meaning, the UNVERIFIED_EMPTY refusal behavior, and the autoRefresh fallback are all disclosed. No annotation contradiction.

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

Conciseness5/5

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

The description is long but every sentence earns its place: it front-loads the core resource, then packs decision-relevant behavior (pagination semantics, sort behavior, complete flag, unverified-empty behavior) in a tight block. No filler or repetition of schema entries.

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 complex 9-parameter, no-output-schema tool, the description covers the operational guardrails needed to call it correctly: freshness, empty-refusal, autoRefresh cost, and result completeness. The one gap is that it does not describe the record fields or response envelope, but with no output schema, a bit more detail about the result payload would round it out; still, the coverage is strong.

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?

The schema already has 100% coverage, so the baseline is 3, and the description adds meaningful semantics beyond schema: the `sort` field's effect on which end of a truncated page is kept, the cache-size motivation for filters vs page-walking, and the precise meaning of `complete` relative to freshness.asOf. It does not restate every schema field, but the added strategic context is substantial.

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: 'List messages from the local OurFamilyWizard cache,' then immediately names filtering dimensions (folder, date range, substring on subject+body). This clearly distinguishes it from sibling tools like ofw_get_message (single message) and ofw_sync_messages (sync operation).

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?

Explicitly tells the agent when to prefer filters over pagination ('if you know what you want (a date range, a topic), prefer the filters over walking pages'), and there is an explicit 'instead of paging to it' alternative. Although sibling alternatives are not named by name, the guidance about cache size and filter-vs-page tradeoff is actionable.

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

Deploy Server

Other Tools