weread-mcp

阅读统计

get_read_stats

Read-only

Get personal reading statistics: total time, reading days, rankings, and preference analysis across weekly, monthly, yearly, or overall periods.

Instructions

获取个人阅读统计（/readdata/detail）：时长、天数、排行、偏好分析。

    **单位与口径（极易出错，必须遵守）**：
    - `totalReadTime` 是该周期总阅读/收听时长，单位**秒**，禁止当成分钟或小时；
      统计总时长优先用它，`readTimes` 只用于明细或交叉校验。
    - `dayAverageReadTime` 是按**自然日**平均的秒数，分母不是 `readDays`；
      需要「阅读日均」要自己用 `totalReadTime / readDays` 算并说明。
    - `readDays` 是有效阅读天数（单日满 1 分钟）。
    - `compare` 是与上一周期日均的比例，0.2 表示约增长 20%。
    - `preferAuthor[].readTime` 是格式化字符串（如「5小时30分钟」），不是秒。
    - `preferTime` 是 24 小时时段分布（秒），顺序从 6 点开始到次日 5 点，不是从 0 点。

    本接口只支持固定自然周期，不能传任意起止日期。跨区间要组合：
    整年用 `annually` 逐年查询并累加，整月用 `monthly`；边界不完整时优先用
    `dailyReadTimes` 做日级扣减，没有日级明细就用月级近似并在回答中说明口径。

    `_computed` 里给出了换算好的「X小时Y分钟」文案。
    失败时回复：阅读数据暂时无法获取，请稍后再试~

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	No	统计维度：weekly=本周，monthly=本月（默认），annually=本年，overall=总计	monthly
`base_time`	No	基准时间戳，0=当前周期。服务端会归一化到周期起点（周一/月初/年初）；查历史就传该周期内任一 Unix 时间戳；overall 固定为 0。

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already state readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds critical behavioral details: it warns that 'dayAverageReadTime' uses a natural-day denominator, not 'readDays', and that 'preferAuthor[].readTime' is a formatted string, not seconds. It also explains the time distribution order and the limitation on date ranges. These details go beyond the annotations and are essential for correct interpretation of results.

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 structured with clear headers (units, periods, computed, failure). It front-loads the most critical warnings about units and periods. Every sentence serves a purpose, either clarifying semantics, providing computation guidance, or specifying error handling. It is comprehensive yet organized, making it easy to scan.

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?

Given the tool's complexity (multiple fields with non-obvious units, fixed-period limitations, and cross-period combination logic), the description is complete. It addresses all potential pitfalls, provides alternative strategies for periods not covered, and even gives guidance on failure responses. The output schema exists, so return values need not be described in detail, but the description covers semantics that the schema cannot convey.

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 input schema already provides comprehensive descriptions for both 'mode' and 'base_time', with enum values and default behavior. The description adds extra context about 'base_time' (normalization to period start) and emphasizes unit pitfalls that are not in the schema. Since schema coverage is 100%, the description's added value is moderate but significant for error prevention, warranting a score above baseline.

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 clearly states the tool's purpose with a specific verb ('获取' = get) and resource ('个人阅读统计' = personal reading stats), and identifies the endpoint. It distinguishes itself from sibling tools like 'get_reading_overview' or 'get_reading_progress' by focusing on statistical aggregates. The purpose is unambiguous.

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?

The description provides explicit when-to-use and when-not-to-use guidance. It states that this tool only supports fixed natural periods and cannot accept arbitrary start/end dates, and it gives concrete alternatives for cross-period queries (using 'annually' for whole years, 'monthly' for months, and 'dailyReadTimes' for boundary adjustments). It also warns about units and provides failure response guidance, making usage conditions crystal clear.

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