homescreen-mcp

Overview Schema Source Related Servers Discussions Admin

screen_time

Reports app usage, top apps, and estimated page swipes from device memory or synced Mac data over a chosen period, helping compare actual use with a draft Home Screen layout.

Instructions

Which apps get used, the top apps with where they are now, and estimated page swipes for the device vs the draft. source='device': the device's own memory reports (no setup; apps iOS keeps running for calls or in memory every day count less, listed under 'background'); source='mac': Screen Time synced to this Mac (Share Across Devices), last days days.

Input Schema

Name	Required	Description	Default
`days`	No
`source`	No		device

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.1.0Nov 3, 2026

addedInput schema / properties / source

Added value: +{
+  "default": "device",
+  "title": "Source",
+  "type": "string"
+}

First observedv1.0.0Oct 31, 2026

TDQS

B3.2/5.0

Behavior3/5

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

With no annotations, the description carries the full burden; it discloses that device source requires no setup, that background apps are counted less and listed under 'background', and that mac source requires Share Across Devices. It does not explicitly state read-only/side-effect behavior, permissions, or failure modes.

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 information-dense but poorly structured and contains ambiguous phrases, especially 'top apps with where they are now' and 'device vs the draft'. It is not excessively long, but wording could be clearer and better front-loaded.

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

Completeness3/5

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

For a two-parameter read tool with an output schema, the description covers data sources, time window, and one important counting caveat. However, it does not explain how this tool relates to the draft or when to use it alongside siblings such as optimize_by_usage, leaving context gaps.

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 description coverage is 0%, so the description must define parameters; it gives meaningful semantics for source values and explains days as the trailing window. It does not state the default or full valid value set, but it adds substantial meaning beyond the bare schema.

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

Purpose3/5

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

The description identifies the resource (screen time/app usage) and lists outputs such as top apps and estimated page swipes, but it never states a clear action verb and phrases like 'where they are now' and 'device vs the draft' are ambiguous. It does not explicitly differentiate this tool from siblings such as optimize_by_usage or read_phone.

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?

It gives useful guidance for choosing source='device' versus source='mac' and notes the last `days` window, but offers no guidance on when to call screen_time instead of related sibling tools. No exclusions or alternatives are mentioned.

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