@josephyan/qingflow-app-builder-mcp 0.2.0-beta.12 → 0.2.0-beta.14

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.12
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.14
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.12 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.14 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.12",
+  "version": "0.2.0-beta.14",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b12"
+version = "0.2.0b14"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-builder/SKILL.md

@@ -17,6 +17,29 @@ Before any write or verification flow, identify whether the task targets `test`
 
 Pick the smallest tool layer that can finish the task.
 
+## Mental Model
+
+Model builder requests in four layers. Do not flatten them.
+
+- `package`: the solution container or app bundle, for example “研发项目管理” or “费控管理系统”
+- `app`: one form/app inside that package, for example “项目”, “需求”, “任务”, “缺陷”, “团队”
+- `field`: one field inside one app
+- `relation`: a field that links one app to another app
+
+Interpret user intent with this hierarchy:
+
+- If the user says “应用包”, “系统”, “包含多个表单”, “多个模块”, or asks for several named forms that relate to each other, treat it as a `package` with multiple `apps`
+- Do not compress a multi-app system into one app with several text fields
+- Names like “项目/需求/任务/缺陷/团队” or “费用申请/预算管理/报销审批” are usually separate apps, not text fields
+- Build the apps first, then add `relation` fields to connect them
+
+Default modeling rules:
+
+- One business object -> one app
+- Attributes of that object -> fields inside that app
+- Another business object -> a separate app, not a text field
+- Cross-object links -> relation fields, not text fields
+
 - Authentication and workspace: `auth_*`, `workspace_*`
 - File upload: `file_upload_local`
 - Resource resolve/read: `package_list`, `package_resolve`, `package_create`, `builder_tool_contract`, `member_search`, `role_search`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`
@@ -45,6 +68,7 @@ Default policy:
 
 - Creating or updating one app inside an existing package: resolve the package/app, read compact state, plan patches on the server, then apply schema/layout/flow/views patches explicitly.
 - If package creation looks necessary or beneficial, ask the user to confirm before calling `package_create`.
+- If the user describes a system/package with multiple forms or modules, do not start with `app_schema_apply` on the package name. Resolve or create the package first, then create each app separately.
 
 ## Standard Operating Order
 
@@ -57,16 +81,19 @@ Before any business tool:
 For builder work:
 
 1. Resolve the target package with `package_resolve`; if resolution is ambiguous or you need a read-only fallback, use `package_list`. If you believe a new package should be created, ask the user to confirm before calling `package_create`.
-2. Resolve the target app with `app_resolve` if the request is an update.
-3. Read only the smallest summary you need: `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`.
-4. Use `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, or `app_views_plan` before any non-trivial write.
-5. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands.
-6. If the app must belong to a package, use `package_attach_app` explicitly after schema work unless readback already shows the target `tag_id`.
-7. Use `app_layout_apply` only when the user is explicitly changing layout. Prefer the default `mode=merge`; use `mode=replace` only when you intend to place every field explicitly. It publishes by default.
-8. Use `app_flow_apply` after schema exists. It publishes by default.
-9. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default.
-10. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
-11. If a write fails with `APP_EDIT_LOCKED`, stop normal writes. Only use `app_release_edit_lock_if_mine` when the failed result shows the lock owner is the current logged-in user.
+2. Decide whether the target is one app or a multi-app package:
+   - one app: continue with `app_resolve`
+   - multi-app package/system: create or resolve the package, then create each app separately before adding relations
+3. Resolve the target app with `app_resolve` if the request is an update.
+4. Read only the smallest summary you need: `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`.
+5. Use `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, or `app_views_plan` before any non-trivial write.
+6. Use `app_schema_apply` for create/upsert/remove field work. It publishes by default after the patch lands.
+7. If the app must belong to a package, use `package_attach_app` explicitly after schema work unless readback already shows the target `tag_id`.
+8. Use `app_layout_apply` only when the user is explicitly changing layout. Prefer the default `mode=merge`; use `mode=replace` only when you intend to place every field explicitly. It publishes by default.
+9. Use `app_flow_apply` after schema exists. It publishes by default.
+10. Use `app_views_apply` when the user wants explicit table/card/board/gantt views. It publishes by default.
+11. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
+12. If a write fails with `APP_EDIT_LOCKED`, stop normal writes. Only use `app_release_edit_lock_if_mine` when the failed result shows the lock owner is the current logged-in user.
 
 For view work, keep the order strict:
 
@@ -86,13 +113,17 @@ For flow work, keep the order strict:
 5. `role_create` if the user wants a reusable role and no suitable role exists yet
 6. Start from a canonical preset when possible
 7. Use patch-style edits to that skeleton instead of freehand full-graph generation
-8. Declare approver/fill/copy assignees explicitly:
+8. When patching a preset skeleton, reuse the preset node ids:
+   - `basic_approval` -> patch `approve_1`
+   - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
+   Do not invent a second approval/fill node id unless you are intentionally replacing the skeleton and removing the preset node.
+9. Declare approver/fill/copy assignees explicitly:
    - prefer `assignees.role_names`
    - support `assignees.member_names` / `assignees.member_emails` / `assignees.member_uids`
-9. When a node must edit specific fields, declare `permissions.editable_fields`
-10. `app_flow_plan`
-11. `app_flow_apply`
-12. `app_read_flow_summary` after apply whenever the user asked for verification or apply returns `partial_success`
+10. When a node must edit specific fields, declare `permissions.editable_fields`
+11. `app_flow_plan`
+12. `app_flow_apply`
+13. `app_read_flow_summary` after apply whenever the user asked for verification or apply returns `partial_success`
 
 In `prod`, keep `plan` and `apply` as separate phases unless the user explicitly asks for a direct live execution.
 
@@ -109,9 +140,11 @@ For additive work on existing systems:
 - `app_schema_apply` is the only public patch tool allowed to create an app shell; `app_layout_apply`, `app_flow_apply`, and `app_views_apply` require an existing app.
 - Prefer `*_plan` before `*_apply`; the plan tools do server-side normalization and return the next executable call skeleton.
 - For abstract requests like “默认视图”, “基础审批流”, “灵活流程”, or “美观布局”, first translate the intent into a stable preset or explicit patch. Do not send those phrases to MCP unchanged.
+- If the user asks for a business system or package that contains several forms, do not use the system/package name as `app_name` and do not try to store the child app names as text fields.
 - For flexible workflow requests, split the work into two steps:
   1. create a base skeleton with a preset
   2. apply explicit business-specific changes as patchable nodes/transitions
+- For preset-based flows, treat preset node ids as part of the public contract. Patch the skeleton nodes by the same ids instead of creating a parallel node with a new id and leaving the preset node unassigned.
 - Approval, fill, and copy nodes must declare at least one assignee. Treat this as a hard requirement, not an optional detail.
 - For workflow nodes, use the canonical public shape:
   - `assignees.role_names`
@@ -123,6 +156,7 @@ For additive work on existing systems:
 - `app_schema_apply` does not treat package attachment as success criteria; if package ownership matters, verify `tag_ids_after` and call `package_attach_app` explicitly.
 - `package_attach_app` is the source of truth for package ownership; do not assume app creation or publish implicitly attaches the app.
 - `relation` and `subtable` must be explicit; do not infer them from vague natural language.
+- Another app is not a field. If two business objects should both have their own records, build two apps and connect them with relation fields.
 - In `prod`, prefer explicit patch tools and avoid any speculative create flow.
 - Never try to bypass collaborative edit locks. `app_release_edit_lock_if_mine` is only for the case where the lock owner is the current authenticated user.
 

package/skills/qingflow-app-builder/references/create-app.md

@@ -2,6 +2,18 @@
 
 Use this when the user wants one new app inside an existing package.
 
+Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
+
+1. resolve or create the package
+2. create each app separately
+3. attach each app to the package
+4. add relation fields between apps
+
+Hierarchy reminder:
+
+- package -> app -> field -> relation
+- another business object is another app, not a text field
+
 If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, call `package_create` before this sequence.
 
 ## Minimal sequence
@@ -13,6 +25,22 @@ If creating a brand new package would help, ask the user to confirm package crea
 5. `package_attach_app`
 6. `app_publish_verify` only when the user asks for explicit final verification
 
+## Multi-app systems are different
+
+If the user says things like:
+
+- “创建一个完整应用包”
+- “包含项目、需求、任务、缺陷、团队这几个表单”
+- “这些表单之间建立关联关系”
+
+then do not treat that as one app.
+
+Use this pattern instead:
+
+1. `package_resolve` or `package_create`
+2. for each app name, run `app_schema_plan -> app_schema_apply -> package_attach_app`
+3. once the apps exist, add `relation` fields between them
+
 ## Example
 
 Create a new package only after the user confirms package creation:
@@ -110,3 +138,11 @@ The create route did not resolve in the current backend route context. Re-run `w
 ### `PACKAGE_ATTACH_FAILED`
 
 Do not retry schema creation. Re-run only `package_attach_app`, then verify with `app_read_summary`.
+
+### Hierarchy modeling mistake
+
+If the user asked for several named forms/apps but the draft patch turns them into text fields inside one app, stop and remodel the task as:
+
+- one package
+- many apps
+- relation fields between those apps

package/skills/qingflow-app-builder/references/gotchas.md

@@ -11,6 +11,13 @@
 - Treat `package_attach_app` as the source of truth for package ownership
 - Check `tag_ids_after` after schema writes
 
+## Package vs app vs field
+
+- A package/system is not an app
+- Another app is not a field
+- If the user names multiple forms/modules that relate to each other, create multiple apps and connect them with relation fields
+- Do not use child app names like “项目/需求/任务/缺陷/团队” as plain text fields inside one app
+
 ## Auto publish
 
 - `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default
@@ -32,6 +39,7 @@
 - Prefer roles over explicit members unless the user explicitly names people
 - Resolve assignees with `role_search` / `member_search` before flow apply
 - Use `permissions.editable_fields` for node-level editable field permissions; do not guess field ids
+- Preset node ids matter. When patching `basic_approval` or `basic_fill_then_approve`, reuse `approve_1` and `fill_1` unless you are explicitly replacing the skeleton.
 - If `app_flow_plan` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
 - Do not switch to hidden `solution_*` tools from public builder flows
 

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -8,6 +8,17 @@ Use the smallest v2 builder tool chain that can finish the task.
 
 Use `plan` before `apply` unless the patch is trivial and already normalized.
 
+## Hierarchy first
+
+Before picking tools, decide which layer the request targets:
+
+- `package`: a solution/app bundle like “研发项目管理” or “费控管理系统”
+- `app`: one form/app inside that package
+- `field`: one field inside one app
+- `relation`: a field that links two apps
+
+If the user asks for multiple forms/modules that relate to each other, this is a package-level multi-app task, not a single-app create.
+
 ## Resolve
 
 - `package_create`: create a new package only after the user confirms package creation; exact-name duplicates return `noop=true`
@@ -57,6 +68,8 @@ These execute normalized patches and publish by default unless `publish=false`.
   `package_resolve -> app_resolve -> app_schema_plan -> app_schema_apply -> package_attach_app`
 - Create a brand new package, then create one app in it:
   `package_create -> package_resolve -> app_schema_plan -> app_schema_apply -> package_attach_app`
+- Create a brand new multi-app system/package:
+  `package_create/resolve -> per-app app_schema_plan/apply -> package_attach_app per app -> relation field patches`
 - Update fields on an existing app:
   `app_resolve -> app_read_fields -> app_schema_plan -> app_schema_apply`
 - Tidy layout:
@@ -71,9 +84,12 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Do not handcraft raw Qingflow schema payloads
 - Do not rely on internal `solution_*` tools in public builder flows
 - Do not create a new package without first asking the user to confirm package creation
+- Do not treat a package/system name as `app_name` when the user clearly wants multiple apps inside it
+- Do not compress multiple business objects into one app with several text fields
 - Do not skip summary reads before flow or view work
 - Do not emit `column_names`; always use `columns`
 - Do not reuse internal flow keys such as `role_entries` or `editable_que_ids` in public builder calls
 - Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
 - Do not omit assignees on approval/fill/copy nodes
+- Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
 - Do not guess role ids, member ids, or editable field ids; resolve names first

package/skills/qingflow-app-builder/references/update-flow.md

@@ -11,9 +11,14 @@ Use this when the app already exists and the task is only about workflow.
 5. `role_create` if the user wants a reusable directory role and no good role exists
 6. start from a canonical preset when possible
 7. patch the skeleton instead of freehanding a full graph
-8. `app_flow_plan`
-9. `app_flow_apply`
-10. `app_read_flow_summary` when apply returns `partial_success` or the user asked for verification
+8. reuse preset node ids when patching:
+   - `basic_approval` -> patch `approve_1`
+   - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
+   Do not add a second approval/fill node with a new id unless you are intentionally replacing the skeleton.
+   The MCP now auto-aligns the simplest single-node preset overrides, but still prefer explicit preset ids so the merged graph stays predictable.
+9. `app_flow_plan`
+10. `app_flow_apply`
+11. `app_read_flow_summary` when apply returns `partial_success` or the user asked for verification
 
 If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
 
@@ -145,6 +150,7 @@ Only after that should you use explicit nodes:
 ```
 
 After `app_flow_plan` succeeds, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite the result into internal fields such as `role_entries` or `editable_que_ids`.
+When you patch a preset, patch the preset node itself. Do not leave the preset approval node unassigned while adding a second custom approval node.
 
 ## Common failures
 
@@ -152,12 +158,19 @@ After `app_flow_plan` succeeds, prefer reusing its `suggested_next_call.argument
 
 Approval, fill, and copy nodes must declare at least one assignee.
 
+If this happens after using a preset, check for this specific mistake first:
+
+- the preset created `approve_1` or `fill_1`
+- your patch created a different node id instead of patching that preset node
+- the original preset node remained in the graph without assignees
+
 Preferred fix order:
 
 1. `role_search`
 2. `member_search` only if the user explicitly named members
 3. `role_create` if the business needs a reusable role
-4. retry `app_flow_plan` or `app_flow_apply` with canonical `assignees.*`
+4. patch the preset node id itself with canonical `assignees.*`
+5. retry `app_flow_plan` or `app_flow_apply`
 
 ### `FLOW_DEPENDENCY_MISSING`
 

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b12"
+__version__ = "0.2.0b14"

package/src/qingflow_mcp/builder_facade/service.py

@@ -3624,6 +3624,11 @@ def _merge_flow_graph(
 ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
     if not override_nodes and not override_transitions:
         return deepcopy(base_nodes), deepcopy(base_transitions)
+    override_nodes, override_transitions = _align_flow_preset_override_ids(
+        base_nodes=base_nodes,
+        override_nodes=override_nodes,
+        override_transitions=override_transitions,
+    )
     merged_nodes: list[dict[str, Any]] = []
     override_map = {
         str(node.get("id") or ""): deepcopy(node)
@@ -3654,6 +3659,72 @@ def _merge_flow_graph(
     return merged_nodes, merged_transitions
 
 
+def _align_flow_preset_override_ids(
+    *,
+    base_nodes: list[dict[str, Any]],
+    override_nodes: list[dict[str, Any]],
+    override_transitions: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Map simple preset skeleton overrides back onto canonical preset node ids.
+
+    This keeps preset-based plans stable when the caller customizes the single
+    approval/fill/copy step semantically but forgets to reuse ids such as
+    `approve_1` or `fill_1`.
+    """
+    patchable_types = {"approve", "fill", "copy"}
+    base_by_type: dict[str, list[str]] = {}
+    override_by_type: dict[str, list[str]] = {}
+    for node in base_nodes:
+        if not isinstance(node, dict):
+            continue
+        node_type = str(node.get("type") or "")
+        node_id = str(node.get("id") or "")
+        if node_type in patchable_types and node_id:
+            base_by_type.setdefault(node_type, []).append(node_id)
+    for node in override_nodes:
+        if not isinstance(node, dict):
+            continue
+        node_type = str(node.get("type") or "")
+        node_id = str(node.get("id") or "")
+        if node_type in patchable_types and node_id:
+            override_by_type.setdefault(node_type, []).append(node_id)
+    replacement_map: dict[str, str] = {}
+    for node_type in patchable_types:
+        base_ids = base_by_type.get(node_type) or []
+        override_ids = override_by_type.get(node_type) or []
+        if len(base_ids) != 1 or len(override_ids) != 1:
+            continue
+        base_id = base_ids[0]
+        override_id = override_ids[0]
+        if override_id == base_id:
+            continue
+        replacement_map[override_id] = base_id
+    if not replacement_map:
+        return deepcopy(override_nodes), deepcopy(override_transitions)
+    aligned_nodes: list[dict[str, Any]] = []
+    for node in override_nodes:
+        if not isinstance(node, dict):
+            continue
+        aligned = deepcopy(node)
+        node_id = str(aligned.get("id") or "")
+        if node_id in replacement_map:
+            aligned["id"] = replacement_map[node_id]
+        aligned_nodes.append(aligned)
+    aligned_transitions: list[dict[str, Any]] = []
+    for transition in override_transitions:
+        if not isinstance(transition, dict):
+            continue
+        aligned = deepcopy(transition)
+        source = str(aligned.get("from") or "")
+        target = str(aligned.get("to") or "")
+        if source in replacement_map:
+            aligned["from"] = replacement_map[source]
+        if target in replacement_map:
+            aligned["to"] = replacement_map[target]
+        aligned_transitions.append(aligned)
+    return aligned_nodes, aligned_transitions
+
+
 def _extract_directory_items(listed: JSONObject) -> list[dict[str, Any]]:
     if isinstance(listed.get("items"), list):
         return [item for item in listed["items"] if isinstance(item, dict)]

package/src/qingflow_mcp/tools/record_tools.py

@@ -16,7 +16,10 @@ from .base import ToolBase
 
 
 DEFAULT_QUERY_PAGE_SIZE = 50
+DEFAULT_ANALYSIS_PAGE_SIZE = 100
 DEFAULT_SCAN_MAX_PAGES = 10
+DEFAULT_ANALYSIS_SCAN_MAX_PAGES = 20
+DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP = 50
 DEFAULT_ROW_LIMIT = 200
 DEFAULT_OUTPUT_PROFILE = "compact"
 MAX_LIST_COLUMN_LIMIT = 20
@@ -208,6 +211,7 @@ class RecordTools(ToolBase):
             page_size: int = DEFAULT_QUERY_PAGE_SIZE,
             requested_pages: int = 1,
             scan_max_pages: int = DEFAULT_SCAN_MAX_PAGES,
+            auto_expand_pages: bool = False,
             query_key: str | None = None,
             filters: list[JSONObject] | None = None,
             sorts: list[JSONObject] | None = None,
@@ -232,6 +236,7 @@ class RecordTools(ToolBase):
                 page_size=page_size,
                 requested_pages=requested_pages,
                 scan_max_pages=scan_max_pages,
+                auto_expand_pages=auto_expand_pages,
                 query_key=query_key,
                 filters=filters or [],
                 sorts=sorts or [],
@@ -261,9 +266,10 @@ class RecordTools(ToolBase):
             amount_column: str | int | None = None,
             metrics: list[str] | None = None,
             page_num: int = 1,
-            page_size: int = DEFAULT_QUERY_PAGE_SIZE,
+            page_size: int = DEFAULT_ANALYSIS_PAGE_SIZE,
             requested_pages: int = 1,
-            scan_max_pages: int = DEFAULT_SCAN_MAX_PAGES,
+            scan_max_pages: int = DEFAULT_ANALYSIS_SCAN_MAX_PAGES,
+            auto_expand_pages: bool = False,
             query_key: str | None = None,
             filters: list[JSONObject] | None = None,
             sorts: list[JSONObject] | None = None,
@@ -286,6 +292,7 @@ class RecordTools(ToolBase):
                 page_size=page_size,
                 requested_pages=requested_pages,
                 scan_max_pages=scan_max_pages,
+                auto_expand_pages=auto_expand_pages,
                 query_key=query_key,
                 filters=filters or [],
                 sorts=sorts or [],
@@ -422,6 +429,7 @@ class RecordTools(ToolBase):
         def runner(session_profile, context):
             field_mapping: list[JSONObject] = []
             view_resolution: JSONObject | None = None
+            resolved_view_selection: ViewSelection | None = None
             if resolve_fields and isinstance(normalized.get("app_key"), str) and normalized.get("app_key"):
                 index = self._get_field_index(profile, context, cast(str, normalized["app_key"]), force_refresh=False)
                 for candidate in _collect_plan_field_candidates(tool, normalized):
@@ -434,6 +442,7 @@ class RecordTools(ToolBase):
                     view_name=_normalize_optional_text(normalized.get("view_name")),
                 )
                 if view_selection is not None:
+                    resolved_view_selection = view_selection
                     view_resolution = {
                         "resolved": True,
                         "view_key": view_selection.view_key,
@@ -441,7 +450,16 @@ class RecordTools(ToolBase):
                         "local_filtering": bool(view_selection.conditions),
                         "condition_group_count": len(view_selection.conditions),
                     }
-            estimate = _build_plan_estimate(tool, normalized)
+            probe = None
+            if tool in {"record_query", "record_aggregate"} and isinstance(normalized.get("app_key"), str) and normalized.get("app_key"):
+                probe = self._build_analysis_probe(
+                    profile,
+                    context,
+                    app_key=cast(str, normalized["app_key"]),
+                    arguments=normalized,
+                    view_selection=resolved_view_selection,
+                )
+            estimate = _build_plan_estimate(tool, normalized, probe=probe)
             readiness = _assess_plan_readiness(tool, normalized, validation, field_mapping, estimate)
             return {
                 "profile": profile,
@@ -458,6 +476,13 @@ class RecordTools(ToolBase):
                     "ready_for_final_conclusion": readiness["ready_for_final_conclusion"],
                     "final_conclusion_blockers": readiness["final_conclusion_blockers"],
                     "recommended_next_actions": readiness["recommended_next_actions"],
+                    "suggested_next_call": {
+                        "tool_name": tool,
+                        "arguments": {
+                            **normalized,
+                            **_callable_analysis_arguments(cast(JSONObject, estimate.get("recommended_arguments") if isinstance(estimate.get("recommended_arguments"), dict) else {})),
+                        },
+                    },
                 },
             }
 
@@ -606,6 +631,7 @@ class RecordTools(ToolBase):
         page_size: int,
         requested_pages: int,
         scan_max_pages: int,
+        auto_expand_pages: bool = False,
         query_key: str | None,
         filters: list[JSONObject],
         sorts: list[JSONObject],
@@ -640,6 +666,7 @@ class RecordTools(ToolBase):
                 page_size=page_size,
                 requested_pages=requested_pages,
                 scan_max_pages=scan_max_pages,
+                auto_expand_pages=auto_expand_pages,
                 query_key=query_key,
                 filters=filters,
                 sorts=sorts,
@@ -687,6 +714,7 @@ class RecordTools(ToolBase):
         page_size: int,
         requested_pages: int,
         scan_max_pages: int,
+        auto_expand_pages: bool = False,
         query_key: str | None,
         filters: list[JSONObject],
         sorts: list[JSONObject],
@@ -725,6 +753,14 @@ class RecordTools(ToolBase):
             has_more = False
             group_stats: dict[str, JSONObject] = {}
             total_amount = 0.0
+            scan_control: JSONObject = {
+                "requested_pages": max(requested_pages, 1),
+                "scan_max_pages": max(scan_max_pages, 1),
+                "auto_expand_pages": auto_expand_pages,
+                "auto_expand_applied": False,
+                "auto_expand_target_pages": pages_to_scan,
+                "auto_expand_page_cap": DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP,
+            }
             while scanned_pages < pages_to_scan:
                 page = self._search_page(
                     context,
@@ -743,6 +779,13 @@ class RecordTools(ToolBase):
                 items = rows if isinstance(rows, list) else []
                 if result_amount is None:
                     result_amount = _effective_total(page, page_size)
+                    pages_to_scan, scan_control = _compute_scan_limit(
+                        requested_pages=requested_pages,
+                        scan_max_pages=scan_max_pages,
+                        auto_expand_pages=auto_expand_pages,
+                        page=page,
+                        page_size=page_size,
+                    )
                 has_more = _page_has_more(page, current_page, page_size, len(items))
                 for item in items:
                     if not isinstance(item, dict):
@@ -828,6 +871,13 @@ class RecordTools(ToolBase):
                     amount_total = _coerce_amount(item.get("amount_total"))
                     item["amount_ratio"] = (amount_total / total_amount) if amount_total is not None else None
             effective_result_amount = scanned_records if view_selection is not None else (result_amount or scanned_records)
+            grouped_count = sum(int(item.get("count") or 0) for item in groups)
+            analysis_counts = _build_analysis_counts(
+                backend_total_count=result_amount,
+                scanned_count=scanned_records,
+                grouped_count=grouped_count,
+                local_filtering=view_selection is not None and bool(view_selection.conditions),
+            )
             completeness = _build_completeness(
                 result_amount=effective_result_amount,
                 returned_items=len(groups),
@@ -846,6 +896,7 @@ class RecordTools(ToolBase):
                     "raw_next_page_token": None,
                     "output_next_page_token": None,
                     "stop_reason": "source_exhausted" if not has_more else "scan_limit",
+                    **scan_control,
                 },
             )
             evidence = {
@@ -859,20 +910,65 @@ class RecordTools(ToolBase):
             }
             if strict_full and not bool(completeness.get("raw_scan_complete")):
                 self._raise_need_more_data(completeness, evidence, "Aggregate result is incomplete; increase requested_pages or scan_max_pages.")
+            analysis_status, raw_scan_complete = _analysis_status_from_completeness(completeness)
+            suggested_next_call = None
+            if analysis_status != "success":
+                suggested_next_call = {
+                    "tool_name": "record_aggregate",
+                    "arguments": {
+                        "app_key": app_key,
+                        "group_by": [field.que_title for field in group_fields],
+                        "page_num": max(page_num, 1),
+                        "page_size": page_size,
+                        "requested_pages": max(requested_pages, 1),
+                        "scan_max_pages": max(scan_max_pages, 1),
+                        "auto_expand_pages": auto_expand_pages,
+                        "query_key": query_key,
+                        "filters": filters,
+                        "sorts": sorts,
+                        "time_range": time_range or {},
+                        "amount_column": amount_field.que_title if amount_field is not None else amount_column,
+                        "metrics": metric_names,
+                        "strict_full": strict_full,
+                        "list_type": list_type,
+                        "view_key": view_selection.view_key if view_selection is not None else view_key,
+                        "view_name": view_selection.view_name if view_selection is not None else view_name,
+                        **_callable_analysis_arguments(
+                            _recommended_analysis_arguments(
+                                tool="record_aggregate",
+                                arguments={
+                                    "page_size": page_size,
+                                    "requested_pages": requested_pages,
+                                    "scan_max_pages": scan_max_pages,
+                                },
+                                probe={"backend_total_count": result_amount},
+                                routed_mode="summary",
+                            )
+                        ),
+                    },
+                }
             response: JSONObject = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "ok": True,
+                "status": analysis_status,
                 "request_route": self._request_route_payload(context),
                 "data": {
                     "app_key": app_key,
+                    "analysis_status": analysis_status,
+                    "safe_for_final_conclusion": raw_scan_complete and bool(strict_full),
                     "view": _view_selection_payload(view_selection),
                     "summary": {
-                        "total_count": scanned_records,
+                        "total_count": effective_result_amount,
+                        "backend_total_count": result_amount,
+                        "scanned_count": scanned_records,
+                        "grouped_count": grouped_count,
                         "total_amount": total_amount if amount_field is not None else None,
                     },
+                    "analysis_counts": analysis_counts,
                     "groups": groups,
                     "completeness": completeness,
+                    "suggested_next_call": suggested_next_call,
                 },
             }
             if output_profile == "verbose":
@@ -1430,6 +1526,7 @@ class RecordTools(ToolBase):
         page_size: int,
         requested_pages: int,
         scan_max_pages: int,
+        auto_expand_pages: bool,
         query_key: str | None,
         filters: list[JSONObject],
         sorts: list[JSONObject],
@@ -1476,6 +1573,14 @@ class RecordTools(ToolBase):
             total_amount = 0.0
             missing_count = 0
             by_day: dict[str, JSONObject] = {}
+            scan_control: JSONObject = {
+                "requested_pages": max(requested_pages, 1),
+                "scan_max_pages": max(scan_max_pages, 1),
+                "auto_expand_pages": auto_expand_pages,
+                "auto_expand_applied": False,
+                "auto_expand_target_pages": min(max(requested_pages, 1), max(scan_max_pages, 1)),
+                "auto_expand_page_cap": DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP,
+            }
             while scanned_pages < scan_limit:
                 page = self._search_page(
                     context,
@@ -1494,6 +1599,13 @@ class RecordTools(ToolBase):
                 items = page_rows if isinstance(page_rows, list) else []
                 if result_amount is None:
                     result_amount = _effective_total(page, page_size)
+                    scan_limit, scan_control = _compute_scan_limit(
+                        requested_pages=requested_pages,
+                        scan_max_pages=scan_max_pages,
+                        auto_expand_pages=auto_expand_pages,
+                        page=page,
+                        page_size=page_size,
+                    )
                 has_more = _page_has_more(page, current_page, page_size, len(items))
                 for item in items:
                     if not isinstance(item, dict):
@@ -1531,6 +1643,12 @@ class RecordTools(ToolBase):
                 current_page += 1
             raw_scan_complete = not has_more
             effective_result_amount = scanned_records if view_selection is not None else max(result_amount or 0, scanned_records)
+            analysis_counts = _build_analysis_counts(
+                backend_total_count=result_amount,
+                scanned_count=scanned_records,
+                grouped_count=len(preview_rows),
+                local_filtering=view_selection is not None and bool(view_selection.conditions),
+            )
             completeness = _build_completeness(
                 result_amount=effective_result_amount,
                 returned_items=len(preview_rows),
@@ -1549,6 +1667,7 @@ class RecordTools(ToolBase):
                     "raw_next_page_token": None,
                     "output_next_page_token": None,
                     "stop_reason": "source_exhausted" if raw_scan_complete else "scan_limit",
+                    **scan_control,
                 },
             )
             evidence = {
@@ -1562,24 +1681,73 @@ class RecordTools(ToolBase):
             }
             if strict_full and not raw_scan_complete:
                 self._raise_need_more_data(completeness, evidence, "Summary is incomplete; increase requested_pages or scan_max_pages.")
+            analysis_status, raw_scan_complete = _analysis_status_from_completeness(completeness)
+            suggested_next_call = None
+            if analysis_status != "success":
+                suggested_next_call = {
+                    "tool_name": "record_query",
+                    "arguments": {
+                        "query_mode": "summary",
+                        "app_key": app_key,
+                        "page_num": max(page_num, 1),
+                        "page_size": page_size,
+                        "requested_pages": max(requested_pages, 1),
+                        "scan_max_pages": max(scan_max_pages, 1),
+                        "auto_expand_pages": auto_expand_pages,
+                        "query_key": query_key,
+                        "filters": filters,
+                        "sorts": sorts,
+                        "max_rows": max_rows,
+                        "max_columns": max_columns,
+                        "select_columns": [field.que_title for field in preview_fields],
+                        "amount_column": amount_field.que_title if amount_field is not None else amount_column,
+                        "time_range": time_range or {},
+                        "stat_policy": stat_policy or {},
+                        "strict_full": strict_full,
+                        "output_profile": output_profile,
+                        "list_type": list_type,
+                        "view_key": view_selection.view_key if view_selection is not None else view_key,
+                        "view_name": view_selection.view_name if view_selection is not None else view_name,
+                        **_callable_analysis_arguments(
+                            _recommended_analysis_arguments(
+                                tool="record_query",
+                                arguments={
+                                    "page_size": page_size,
+                                    "requested_pages": requested_pages,
+                                    "scan_max_pages": scan_max_pages,
+                                },
+                                probe={"backend_total_count": result_amount},
+                                routed_mode="summary",
+                            )
+                        ),
+                    },
+                }
             response: JSONObject = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "ok": True,
+                "status": analysis_status,
                 "request_route": self._request_route_payload(context),
                 "data": {
                     "mode": "summary",
+                    "analysis_status": analysis_status,
+                    "safe_for_final_conclusion": raw_scan_complete and bool(strict_full),
                     "source_tool": "record_search",
                     "view": _view_selection_payload(view_selection),
                     "summary": {
                         "summary": {
-                            "total_count": scanned_records,
+                            "total_count": effective_result_amount,
+                            "backend_total_count": result_amount,
+                            "scanned_count": scanned_records,
+                            "preview_row_count": len(preview_rows),
                             "total_amount": total_amount if amount_field is not None else None,
                             "by_day": sorted(by_day.values(), key=lambda item: str(item.get("day"))),
                             "missing_count": missing_count,
                         },
+                        "analysis_counts": analysis_counts,
                         "rows": preview_rows,
                         "completeness": completeness,
+                        "suggested_next_call": suggested_next_call,
                         "applied_limits": {
                             "row_cap": max_rows,
                             "column_cap": resolved_column_cap,
@@ -1721,6 +1889,55 @@ class RecordTools(ToolBase):
                 return True
         return False
 
+    def _build_analysis_probe(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        arguments: JSONObject,
+        view_selection: ViewSelection | None,
+    ) -> JSONObject:
+        page_size = max(_coerce_count(arguments.get("page_size")) or DEFAULT_QUERY_PAGE_SIZE, 1)
+        query_key = _normalize_optional_text(arguments.get("query_key"))
+        filters = _as_object_list(arguments.get("filters"))
+        sorts = _as_object_list(arguments.get("sorts"))
+        app_form = self._get_field_index(profile, context, app_key, force_refresh=False)
+        time_range = cast(JSONObject, arguments.get("time_range") if isinstance(arguments.get("time_range"), dict) else {})
+        match_rules = self._resolve_match_rules(context, filters, app_form)
+        sort_rules = self._resolve_sorts(sorts, app_form)
+        time_field = self._resolve_time_range_column(time_range, app_form)
+        match_rules = self._append_time_range_filter(match_rules, time_range, time_field)
+        probe_page = self._search_page(
+            context,
+            app_key=app_key,
+            page_num=max(_coerce_count(arguments.get("page_num")) or 1, 1),
+            page_size=page_size,
+            query_key=query_key,
+            match_rules=match_rules,
+            sorts=sort_rules,
+            search_que_ids=None,
+            list_type=_coerce_count(arguments.get("list_type")) or DEFAULT_RECORD_LIST_TYPE,
+        )
+        backend_total_count = _effective_total(probe_page, page_size)
+        page_amount = _coerce_count(probe_page.get("pageAmount"))
+        estimated_full_scan_pages = page_amount
+        if estimated_full_scan_pages is None and backend_total_count > 0:
+            estimated_full_scan_pages = (backend_total_count + page_size - 1) // page_size
+        current_budget = min(
+            max(_coerce_count(arguments.get("requested_pages")) or 1, 1),
+            max(_coerce_count(arguments.get("scan_max_pages")) or 1, 1),
+        )
+        return {
+            "page_size": page_size,
+            "backend_total_count": backend_total_count,
+            "backend_page_amount": page_amount,
+            "estimated_full_scan_pages": estimated_full_scan_pages,
+            "current_scan_budget": current_budget,
+            "would_exceed_current_budget": bool(estimated_full_scan_pages is not None and estimated_full_scan_pages > current_budget),
+            "local_filtering": bool(view_selection.conditions) if view_selection is not None else False,
+        }
+
     def _search_page(
         self,
         context,  # type: ignore[no-untyped-def]
@@ -2920,6 +3137,7 @@ def _normalize_plan_arguments(tool: str, arguments: JSONObject) -> JSONObject:
         "pageSize": "page_size",
         "requestedPages": "requested_pages",
         "scanMaxPages": "scan_max_pages",
+        "autoExpandPages": "auto_expand_pages",
         "queryKey": "query_key",
         "maxRows": "max_rows",
         "maxColumns": "max_columns",
@@ -2976,7 +3194,7 @@ def _collect_plan_field_candidates(tool: str, arguments: JSONObject) -> list[JSO
     return candidates
 
 
-def _build_plan_estimate(tool: str, arguments: JSONObject) -> JSONObject:
+def _build_plan_estimate(tool: str, arguments: JSONObject, *, probe: JSONObject | None = None) -> JSONObject:
     page_size = _coerce_count(arguments.get("page_size")) or DEFAULT_QUERY_PAGE_SIZE
     requested_pages = _coerce_count(arguments.get("requested_pages")) or 1
     scan_max_pages = _coerce_count(arguments.get("scan_max_pages")) or requested_pages
@@ -2995,6 +3213,17 @@ def _build_plan_estimate(tool: str, arguments: JSONObject) -> JSONObject:
         )
         if routed_mode == "list":
             reasons.append("list mode is not a safe final-analysis endpoint")
+    recommended_arguments = _recommended_analysis_arguments(
+        tool=tool,
+        arguments=arguments,
+        probe=probe,
+        routed_mode=routed_mode if tool == "record_query" else "summary",
+    )
+    if probe and probe.get("backend_total_count") is not None and probe.get("estimated_full_scan_pages") is not None:
+        estimated_scan_pages = max(estimated_scan_pages, min(int(probe["estimated_full_scan_pages"]), _coerce_count(recommended_arguments.get("scan_max_pages")) or estimated_scan_pages))
+        if bool(probe.get("would_exceed_current_budget")):
+            may_hit_limits = True
+            reasons.append("matching rows appear to exceed the current scan budget")
     return {
         "page_size": page_size,
         "requested_pages": requested_pages,
@@ -3003,10 +3232,51 @@ def _build_plan_estimate(tool: str, arguments: JSONObject) -> JSONObject:
         "estimated_items_upper_bound": page_size * estimated_scan_pages,
         "may_hit_limits": may_hit_limits,
         "reasons": reasons,
-        "probe": None,
+        "probe": probe,
+        "recommended_arguments": recommended_arguments,
     }
 
 
+def _recommended_analysis_arguments(
+    *,
+    tool: str,
+    arguments: JSONObject,
+    probe: JSONObject | None,
+    routed_mode: str,
+) -> JSONObject:
+    base_page_size = _coerce_count(arguments.get("page_size")) or DEFAULT_QUERY_PAGE_SIZE
+    base_requested_pages = _coerce_count(arguments.get("requested_pages")) or 1
+    base_scan_max_pages = _coerce_count(arguments.get("scan_max_pages")) or base_requested_pages
+    if tool == "record_aggregate" or routed_mode == "summary":
+        recommended_page_size = max(base_page_size, DEFAULT_ANALYSIS_PAGE_SIZE)
+        recommended_scan_max_pages = max(base_scan_max_pages, DEFAULT_ANALYSIS_SCAN_MAX_PAGES)
+    else:
+        recommended_page_size = base_page_size
+        recommended_scan_max_pages = base_scan_max_pages
+    backend_total_count = _coerce_count(probe.get("backend_total_count") if isinstance(probe, dict) else None)
+    if backend_total_count is not None and backend_total_count > 0:
+        estimated_full_scan_pages = (backend_total_count + recommended_page_size - 1) // recommended_page_size
+        recommended_requested_pages = max(base_requested_pages, estimated_full_scan_pages)
+        recommended_scan_max_pages = max(recommended_scan_max_pages, estimated_full_scan_pages)
+    else:
+        recommended_requested_pages = base_requested_pages
+        estimated_full_scan_pages = None
+    return {
+        "page_size": recommended_page_size,
+        "requested_pages": recommended_requested_pages,
+        "scan_max_pages": recommended_scan_max_pages,
+        "strict_full": True,
+        "auto_expand_pages": True,
+        "estimated_full_scan_pages": estimated_full_scan_pages,
+    }
+
+
+def _callable_analysis_arguments(arguments: JSONObject) -> JSONObject:
+    if not isinstance(arguments, dict):
+        return {}
+    return {key: value for key, value in arguments.items() if key not in {"estimated_full_scan_pages"}}
+
+
 def _assess_plan_readiness(
     tool: str,
     arguments: JSONObject,
@@ -3039,6 +3309,10 @@ def _assess_plan_readiness(
     if tool in {"record_query", "record_aggregate"} and not bool(arguments.get("strict_full")):
         blockers.append("strict_full should be true for final conclusions")
         actions.append("Set strict_full=true so incomplete scans block final conclusions.")
+    probe = estimate.get("probe") if isinstance(estimate.get("probe"), dict) else None
+    if isinstance(probe, dict) and bool(probe.get("would_exceed_current_budget")):
+        blockers.append("current scan budget is smaller than the estimated matching dataset")
+        actions.append("Use estimate.recommended_arguments or enable auto_expand_pages before trusting aggregate or summary results.")
     actions.append("After execution, verify completeness before using the result as a final conclusion.")
     return {
         "ready_for_final_conclusion": not blockers,
@@ -3154,6 +3428,69 @@ def _view_selection_payload(view_selection: ViewSelection | None) -> JSONObject
     }
 
 
+def _compute_scan_limit(
+    *,
+    requested_pages: int,
+    scan_max_pages: int,
+    auto_expand_pages: bool,
+    page: JSONObject | None = None,
+    page_size: int | None = None,
+) -> tuple[int, JSONObject]:
+    base_requested = max(requested_pages, 1)
+    base_scan_max = max(scan_max_pages, 1)
+    initial_limit = min(base_requested, base_scan_max)
+    meta: JSONObject = {
+        "requested_pages": base_requested,
+        "scan_max_pages": base_scan_max,
+        "auto_expand_pages": auto_expand_pages,
+        "auto_expand_applied": False,
+        "auto_expand_target_pages": initial_limit,
+        "auto_expand_page_cap": DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP,
+    }
+    if not auto_expand_pages or not isinstance(page, dict):
+        return initial_limit, meta
+    effective_page_size = max(page_size or 0, 1)
+    backend_total = _effective_total(page, effective_page_size)
+    page_amount = _coerce_count(page.get("pageAmount"))
+    target_pages = page_amount
+    if target_pages is None and backend_total > 0:
+        target_pages = (backend_total + effective_page_size - 1) // effective_page_size
+    if target_pages is None:
+        return initial_limit, meta
+    expanded_limit = min(max(initial_limit, target_pages), DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP)
+    if expanded_limit > initial_limit:
+        meta["auto_expand_applied"] = True
+    meta["auto_expand_target_pages"] = target_pages
+    meta["backend_total_count"] = backend_total
+    meta["backend_page_amount"] = page_amount
+    return expanded_limit, meta
+
+
+def _build_analysis_counts(
+    *,
+    backend_total_count: int | None,
+    scanned_count: int,
+    grouped_count: int,
+    local_filtering: bool,
+) -> JSONObject:
+    unscanned_count: int | None = None
+    if backend_total_count is not None and not local_filtering:
+        unscanned_count = max(backend_total_count - scanned_count, 0)
+    return {
+        "backend_total_count": backend_total_count,
+        "scanned_count": scanned_count,
+        "grouped_count": grouped_count,
+        "unscanned_count": unscanned_count,
+        "local_filtering": local_filtering,
+    }
+
+
+def _analysis_status_from_completeness(completeness: JSONObject) -> tuple[str, bool]:
+    raw_scan_complete = bool(completeness.get("raw_scan_complete"))
+    status = "success" if raw_scan_complete else "partial_success"
+    return status, raw_scan_complete
+
+
 def _build_completeness(
     *,
     result_amount: int,