Skip to main content
Glama
kingdee-k3cloud-mcp

kingdee-k3cloud-mcp

query_bill_range

Query bill data across date ranges by automatically splitting ranges into chunks and paging each segment, returning small results inline or streaming large exports to a file.

Instructions

按日期自动切片 + 翻页,适合跨月/跨年查询。

将 [date_from, date_to) 按 chunk 切成 N 段,每段独立翻页拉取。 output_path 为空时内联返回(受 MCP 1 MB 限制,适合小跨度); 非空时只接受文件名,流式写入 KD_EXPORT_DIR 或本实例的独立临时目录, 不覆盖已有文件。使用返回的 path 读取文件,适合大跨度(年级)查询。

返回格式(内联): {"rows": [...], "row_count": N, "chunks": K, "exhausted": true} 返回格式(落盘): {"path": "...", "row_count": N, "bytes": M, "chunks": K, "format": "ndjson"} 若中途出错:{"error": "...", "path": "...", "row_count": <已写入>, "bytes": M}

Args: form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder 等 field_keys: 查询字段,逗号分隔 date_field: 日期字段名。通常是 FDate 或 FCreateDate date_from: 起始日期(含),YYYY-MM-DD date_to: 结束日期(不含),YYYY-MM-DD extra_filter: 额外过滤条件(与日期条件 AND 拼接) chunk: 切片粒度,month(默认)/ week / day output_path: 输出文件名,如 "orders.ndjson";不可包含目录。空=内联返回 page_size: 每页行数,默认 2000

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "form_id": "<form_id>",
      "field_keys": "<field_keys>",
      "date_field": "<date_field>",
      "date_from": "<date_from>",
      "date_to": "<date_to>"
    },
    "name": "query_bill_range"
  }
}

Input Schema

NameRequiredDescriptionDefault
chunkNomonth
date_toYes
form_idYes
date_fromYes
page_sizeNo
date_fieldYes
field_keysYes
output_pathNo
extra_filterNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.2

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations at all, the description carries the full burden and discharges it well: half-open interval semantics, per-chunk independent pagination, the 1 MB inline cap, the rule that output_path accepts a bare filename only (no directories), writes go to KD_EXPORT_DIR or a per-instance temp dir, existing files are never overwritten, and a mid-run failure returns an error payload carrying partial row_count/bytes. That is behavioral detail an agent could not infer from the schema.

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 one-line summary, then behavior, then return shapes, then a per-argument list — a sensible order for a 9-parameter tool. It is long, but nearly every line carries information given the empty schema; the only waste is repeating return formats that an output schema already documents.

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 high-complexity, 9-parameter, zero-annotation tool the description is close to sufficient: it covers slicing, pagination, output modes, error payloads and every argument. Remaining gaps are permission/prerequisite information and how it relates to the other query_bill* siblings, both of which matter when an agent is choosing among fourteen tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and the Args block documents all nine parameters: form_id with concrete examples (SAL_SaleOrder, PUR_PurchaseOrder), comma-separated field_keys, typical date_field values (FDate/FCreateDate), inclusive date_from versus exclusive date_to, chunk's enum-like values with month as default, the directory restriction on output_path, and page_size default 2000. This fully covers the gap left by bare schema titles.

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?

The first line states a specific verb and mechanism: slice the [date_from, date_to) interval by chunk and paginate each slice, aimed at cross-month/cross-year queries. An agent can tell this is a range-scan variant of bill querying, though it never names the sibling tools it differs from (e.g. query_bill_all or query_bill_to_file), even though its file-output mode overlaps with the latter.

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?

It states the intended context ('适合跨月/跨年查询') and gives an explicit decision rule between inline output (small spans, 1 MB MCP limit) and file output (large, year-scale spans). What is missing is any exclusion or named alternative for the case where the caller should use a plain single-window query tool instead.

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