diff --git a/README.md b/README.md
index fa3ccdd..ae7a1c5 100644
--- a/README.md
+++ b/README.md
@@ -166,6 +166,9 @@ To configure the MCP server for Gitea, add the following to your MCP configurati
 > You can provide your Gitea host and access token either as command-line arguments or environment variables.
 > Command-line arguments have the highest priority
 
+> [!NOTE]
+> Many tools support `page` and `perPage` parameters for pagination. The maximum effective page size is determined by the Gitea server's `[api].MAX_RESPONSE_ITEMS` setting (default: **50**). Requesting a `perPage` value higher than this limit will be silently capped by the server.
+
 Once everything is set up, try typing the following in your MCP-compatible chatbox:
 
 ```text
diff --git a/README.zh-cn.md b/README.zh-cn.md
index 86485ae..f9266ec 100644
--- a/README.zh-cn.md
+++ b/README.zh-cn.md
@@ -163,9 +163,12 @@ cp gitea-mcp /usr/local/bin/
 **默认日志路径**: `$HOME/.gitea-mcp/gitea-mcp.log`
 
 > [!注意]
-> 可通过命令行参数或环境变量提供 Gitea 主机和访问令牌。  
+> 可通过命令行参数或环境变量提供 Gitea 主机和访问令牌。
 > 命令行参数优先。
 
+> [!注意]
+> 许多工具支持 `page` 和 `perPage` 分页参数。最大有效页面大小由 Gitea 服务器的 `[api].MAX_RESPONSE_ITEMS` 设置决定（默认值：**50**）。请求超过此限制的 `perPage` 值将被服务器静默截断。
+
 一切设置完成后，可在 MCP 聊天框输入：
 
 ```text
diff --git a/README.zh-tw.md b/README.zh-tw.md
index 2dac558..6566353 100644
--- a/README.zh-tw.md
+++ b/README.zh-tw.md
@@ -163,9 +163,12 @@ cp gitea-mcp /usr/local/bin/
 **預設日誌路徑**: `$HOME/.gitea-mcp/gitea-mcp.log`
 
 > [!注意]
-> 可用命令列參數或環境變數提供 Gitea 主機與存取令牌。  
+> 可用命令列參數或環境變數提供 Gitea 主機與存取令牌。
 > 命令列參數優先。
 
+> [!注意]
+> 許多工具支援 `page` 和 `perPage` 分頁參數。最大有效頁面大小由 Gitea 伺服器的 `[api].MAX_RESPONSE_ITEMS` 設定決定（預設值：**50**）。請求超過此限制的 `perPage` 值將被伺服器靜默截斷。
+
 一切設定完成後，可在 MCP 聊天框輸入：
 
 ```text
diff --git a/operation/actions/config.go b/operation/actions/config.go
index 478f298..b8020b5 100644
--- a/operation/actions/config.go
+++ b/operation/actions/config.go
@@ -54,7 +54,7 @@ var (
 		mcp.WithString("org", mcp.Description("organization name (required for org methods)")),
 		mcp.WithString("name", mcp.Description("variable name (required for get methods)")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	ActionsConfigWriteTool = mcp.NewTool(
diff --git a/operation/actions/runs.go b/operation/actions/runs.go
index 9f20fa9..021ec3d 100644
--- a/operation/actions/runs.go
+++ b/operation/actions/runs.go
@@ -39,7 +39,7 @@ var (
 		mcp.WithNumber("max_bytes", mcp.Description("max bytes to return (for 'get_job_log_preview')"), mcp.DefaultNumber(65536), mcp.Min(1024)),
 		mcp.WithString("output_path", mcp.Description("output file path (for 'download_job_log')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	ActionsRunWriteTool = mcp.NewTool(
diff --git a/operation/issue/issue.go b/operation/issue/issue.go
index 4d33f1b..48174e0 100644
--- a/operation/issue/issue.go
+++ b/operation/issue/issue.go
@@ -34,7 +34,7 @@ var (
 		mcp.WithString("since", mcp.Description("filter issues updated after this ISO 8601 timestamp")),
 		mcp.WithString("before", mcp.Description("filter issues updated before this ISO 8601 timestamp")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	IssueReadTool = mcp.NewTool(
diff --git a/operation/label/label.go b/operation/label/label.go
index b9c6fe6..c92f6b1 100644
--- a/operation/label/label.go
+++ b/operation/label/label.go
@@ -32,7 +32,7 @@ var (
 		mcp.WithString("org", mcp.Description("organization name (required for 'list_org')")),
 		mcp.WithNumber("id", mcp.Description("label ID (required for 'get_repo')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	LabelWriteTool = mcp.NewTool(
diff --git a/operation/milestone/milestone.go b/operation/milestone/milestone.go
index 1d6ca9a..af7fbe0 100644
--- a/operation/milestone/milestone.go
+++ b/operation/milestone/milestone.go
@@ -33,7 +33,7 @@ var (
 		mcp.WithString("state", mcp.Description("milestone state (for 'list')"), mcp.DefaultString("all")),
 		mcp.WithString("name", mcp.Description("milestone name filter (for 'list')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	MilestoneWriteTool = mcp.NewTool(
diff --git a/operation/pull/pull.go b/operation/pull/pull.go
index d0fbebd..f8d573b 100644
--- a/operation/pull/pull.go
+++ b/operation/pull/pull.go
@@ -35,7 +35,7 @@ var (
 		mcp.WithString("sort", mcp.Description("sort"), mcp.Enum("oldest", "recentupdate", "leastupdate", "mostcomment", "leastcomment", "priority"), mcp.DefaultString("recentupdate")),
 		mcp.WithNumber("milestone", mcp.Description("milestone")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	PullRequestReadTool = mcp.NewTool(
@@ -48,7 +48,7 @@ var (
 		mcp.WithNumber("review_id", mcp.Description("review ID (required for 'get_review', 'get_review_comments')")),
 		mcp.WithBoolean("binary", mcp.Description("whether to include binary file changes (for 'get_diff')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	PullRequestWriteTool = mcp.NewTool(
diff --git a/operation/repo/branch.go b/operation/repo/branch.go
index 37e54ca..b702d7a 100644
--- a/operation/repo/branch.go
+++ b/operation/repo/branch.go
@@ -44,7 +44,7 @@ var (
 		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
 		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 )
 
diff --git a/operation/repo/commit.go b/operation/repo/commit.go
index 2a8d8e4..8929b3d 100644
--- a/operation/repo/commit.go
+++ b/operation/repo/commit.go
@@ -28,7 +28,7 @@ var (
 		mcp.WithString("sha", mcp.Description("SHA or branch to start listing commits from")),
 		mcp.WithString("path", mcp.Description("path indicates that only commits that include the path's file/dir should be returned.")),
 		mcp.WithNumber("page", mcp.Required(), mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Required(), mcp.Description("results per page"), mcp.DefaultNumber(30), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Required(), mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	GetCommitTool = mcp.NewTool(
diff --git a/operation/repo/release.go b/operation/repo/release.go
index 44928a7..e93dcc8 100644
--- a/operation/repo/release.go
+++ b/operation/repo/release.go
@@ -67,7 +67,7 @@ var (
 		mcp.WithBoolean("is_draft", mcp.Description("Whether the release is draft"), mcp.DefaultBool(false)),
 		mcp.WithBoolean("is_pre_release", mcp.Description("Whether the release is pre-release"), mcp.DefaultBool(false)),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(20), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(20), mcp.Min(1)),
 	)
 )
 
diff --git a/operation/repo/repo.go b/operation/repo/repo.go
index 174c6d3..9140803 100644
--- a/operation/repo/repo.go
+++ b/operation/repo/repo.go
@@ -57,7 +57,7 @@ var (
 		ListMyReposToolName,
 		mcp.WithDescription("List my repositories"),
 		mcp.WithNumber("page", mcp.Required(), mcp.Description("Page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Required(), mcp.Description("results per page"), mcp.DefaultNumber(30), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Required(), mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	ListOrgReposTool = mcp.NewTool(
diff --git a/operation/repo/tag.go b/operation/repo/tag.go
index ee97f38..6338fbd 100644
--- a/operation/repo/tag.go
+++ b/operation/repo/tag.go
@@ -54,7 +54,7 @@ var (
 		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
 		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(20), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(20), mcp.Min(1)),
 	)
 )
 
diff --git a/operation/repo/tree.go b/operation/repo/tree.go
index cf7bbef..6b6e536 100644
--- a/operation/repo/tree.go
+++ b/operation/repo/tree.go
@@ -26,7 +26,7 @@ var GetRepoTreeTool = mcp.NewTool(
 	mcp.WithString("tree_sha", mcp.Required(), mcp.Description("SHA, branch name, or tag name")),
 	mcp.WithBoolean("recursive", mcp.Description("whether to get the tree recursively")),
 	mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-	mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+	mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 )
 
 func init() {
diff --git a/operation/search/search.go b/operation/search/search.go
index 1272ea8..bdc8f88 100644
--- a/operation/search/search.go
+++ b/operation/search/search.go
@@ -31,7 +31,7 @@ var (
 		mcp.WithDescription("search users"),
 		mcp.WithString("keyword", mcp.Required(), mcp.Description("Keyword")),
 		mcp.WithNumber("page", mcp.Description("Page"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	SearOrgTeamsTool = mcp.NewTool(
@@ -41,7 +41,7 @@ var (
 		mcp.WithString("query", mcp.Required(), mcp.Description("search organization teams")),
 		mcp.WithBoolean("includeDescription", mcp.Description("include description?")),
 		mcp.WithNumber("page", mcp.Description("Page"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	SearchReposTool = mcp.NewTool(
@@ -56,7 +56,7 @@ var (
 		mcp.WithString("sort", mcp.Description("Sort")),
 		mcp.WithString("order", mcp.Description("Order")),
 		mcp.WithNumber("page", mcp.Description("Page"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	SearchIssuesTool = mcp.NewTool(
@@ -68,7 +68,7 @@ var (
 		mcp.WithString("labels", mcp.Description("comma-separated list of label names")),
 		mcp.WithString("owner", mcp.Description("filter by repository owner")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 )
 
diff --git a/operation/timetracking/timetracking.go b/operation/timetracking/timetracking.go
index e22fbf2..8a4aa78 100644
--- a/operation/timetracking/timetracking.go
+++ b/operation/timetracking/timetracking.go
@@ -32,7 +32,7 @@ var (
 		mcp.WithString("repo", mcp.Description("repository name (required for 'list_issue_times', 'list_repo_times')")),
 		mcp.WithNumber("index", mcp.Description("issue index (required for 'list_issue_times')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	TimetrackingWriteTool = mcp.NewTool(
diff --git a/operation/user/user.go b/operation/user/user.go
index c0c6e02..0271ece 100644
--- a/operation/user/user.go
+++ b/operation/user/user.go
@@ -44,7 +44,7 @@ var (
 		GetUserOrgsToolName,
 		mcp.WithDescription("Get organizations associated with the authenticated user"),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(defaultPage)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(defaultPageSize)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(defaultPageSize)),
 	)
 )