Server Quality Checklist

Tool Scores

• messages_list_chatsA
  3.6/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does reasonably well: it discloses the local-database source, the SCOPE failure condition tied to MESSAGES_SCOPE / MESSAGES_ALLOW_UNSCOPED, the returned fields, and an explicit exclusion ('Does not return attachment bytes'). It stops short of permissions or pagination behavior beyond the limit parameter.

  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?

  Purpose is front-loaded and the return-value sentence earns its place, but the SCOPE sentence ('No MESSAGES_SCOPE and MESSAGES_ALLOW_UNSCOPED is unset') is grammatically broken and ambiguous, and the enumeration of sibling tools adds noise rather than routing guidance.

  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?

  With no output schema and no annotations, the description compensates by naming the returned fields and the SCOPE error condition, which is enough for an agent to call it and interpret results. Minor gaps remain around ordering of 'recent' conversations and the absence of explicit sibling routing.

  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?

  Schema description coverage is 100% (limit and query both documented in-schema), so the baseline is 3. The description adds no additional meaning for either parameter, for example what counts as a match for 'query'.

  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?

  States a specific verb and resource ('List recent conversations') and scopes it precisely to the local Messages database covering iMessage and SMS. It alludes to sibling tools ('list/search/thread/send/watch') but does not name them directly, so differentiation from messages_search and messages_get_thread requires inference.

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

  Usage Guidelines3/5

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

  Offers one concrete usage tip ('Prefer guid to remember a thread across launches') but never says when to choose this tool over messages_search or messages_get_thread. Usage is implied by the 'recent conversations' framing rather than stated as an explicit rule.

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

• messages_get_threadA
  3.7/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does meaningful work: page ordering, attachment metadata present but bytes absent, and tapbacks omitted unless include_reactions is true. It omits operational traits such as pagination termination and error behavior when the chat cannot be resolved, so it is strong but not exhaustive.

  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 opening sentence is front-loaded and efficient, but the second sentence ('No MESSAGES_SCOPE and MESSAGES_ALLOW_UNSCOPED is unset; list/search/thread/send/watch return SCOPE') is cryptic jargon-heavy shorthand that resists parsing and interrupts the flow between purpose and identity resolution.

  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 7-parameter, all-optional, no-output-schema, no-annotation tool, the description covers identity resolution, pagination, date filtering, and reaction handling adequately. It leaves a gap around what happens on unresolved chats or empty results, but nothing essential for correct invocation is missing.

  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 is 3, and the description earns credit by clarifying that 'before' accepts either a message_id or an ISO timestamp and that from_date/to_date filter on the converted Apple date. It also spells out that guid can arrive via the handle field or chat_id, adding meaning beyond the schema labels.

  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?

  States a specific verb and resource ('Return messages for one chat') plus an ordering guarantee ('oldest-first within the page'), which is enough to distinguish it from messages_list_chats. However, it never explicitly contrasts itself with messages_search, the sibling most likely to be confused with a message-retrieval tool.

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

  Usage Guidelines3/5

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

  Gives conditional guidance for identity resolution (chat_id, guid, or participant handle) and the single-chat fallback when nothing is supplied, which is genuinely useful. It does not say when to prefer this tool over messages_search or messages_list_chats, so alternative selection is left implicit.

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

• messages_searchA
  3.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 full burden and does substantial work: it discloses scope/permission failure behavior ("No MESSAGES_SCOPE... list/search/thread/send/watch return SCOPE"), truncation semantics ("Returns truncated:true and scanned when the Tahoe window is exhausted"), coverage limits (no attachment binaries), and a no-write guarantee ("Does not write FTS into chat.db"). It stops short of stating auth requirements or result ordering, so it is strong but not exhaustive.

  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?

  It is front-loaded with the search semantics and each sentence carries behavioral information rather than repeating the schema. A few internals ("Tahoe rows", "chat.db", "FTS") are implementation jargon that does not help an agent select the tool, which is the main source of bloat.

  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?

  With no annotations and no output schema, the description must supply the full picture, and it covers permission errors, truncation return fields (truncated, scanned), and search coverage. What remains thin is result ordering/pagination shape across large result sets, but for a 5-param search tool this is close to complete.

  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 is 3; the description adds genuine meaning on top of the schema by clarifying that matching is case-insensitive (query) and that omitting chat_id widens the search to all readable chats or the allowlist. It does not elaborate on date-bound inclusivity beyond what the schema already says.

  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?

  "Search message text" states a specific verb and resource, and the mechanics (LIKE on plain-text column plus decode-scan) make the operation concrete. It never names the sibling tools (messages_get_thread, messages_list_chats), so the agent must infer the boundary between searching messages and fetching a thread, which keeps it out of 5 territory.

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

  Usage Guidelines3/5

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

  The description gives one clear conditional: "With no chat_id, searches across all readable chats (or the allowlist)", which tells the agent how to broaden scope. However, there is no explicit when-to-use-this-vs-messages_get_thread or messages_list_chats guidance, so routing between siblings is only implied.

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

• messages_statusA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does real work: it discloses that message bodies are never returned, that it surfaces a likely-missing Full Disk Access condition, and that 'unscoped' is gated on MESSAGES_ALLOW_UNSCOPED=1. It omits cost/latency and read-only confirmation, but for a zero-parameter status probe this is solid coverage.

  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?

  Front-loaded with the core verb ('Report whether...') and packs many diagnostics into one tight sentence, followed by the usage cue and two exclusion/semantics notes. Every clause carries information, though the MESSAGES_ALLOW_UNSCOPED sentence is a fine-grained detail.

  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?

  There is no output schema, so the description must describe what comes back — and it enumerates the returned status fields explicitly. For a no-parameter, no-annotation diagnostic tool, nothing an agent needs to call it correctly is missing.

  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 tool takes no parameters, so there is no parameter semantics to document. Baseline 4 applies for a zero-parameter definition.

  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?

  States a specific verb ('Report') and enumerates the exact diagnostics it returns: db readability, Full Disk Access status, macOS hints, send/redact flags, snapshot size/age, and inbox scoping. This is clearly distinct from the sibling list/search/thread tools, which handle message content rather than health status.

  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?

  'Call this first when anything fails' gives an explicit, actionable trigger condition. It doesn't name specific alternatives or state when-not-to-use, but the diagnostic nature makes the boundary with the content-reading siblings self-evident.

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