CNEquity — China A-Share Data Lake for AI Agents

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

Annotations only declare readOnlyHint=true; the description adds substantial behavior beyond that: it is cheap and reads no data, it discloses live_mode where answers come from the vendor rather than the lake and are labeled as such, and it explains that coverage bounds are the mechanism for absence-vs-nonexistence. That is real operational context an agent cannot get from the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with 'START HERE' and the core return contract before any routing detail. Despite being several sentences, each one carries load: return contents, coverage semantics, live_mode caveat, then the sibling routing table.

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

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

No output schema exists, so the description carries the return-value burden and does so — it enumerates datasets, coverage window, history mode, freshness, and the query contract, plus live_mode. For a zero-required-param orientation tool, nothing an agent needs before calling is missing.

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

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

Schema description coverage is 100% for the single include_empty parameter, and its own schema description already explains the empty-vs-unknown distinction. The description adds nothing further about the parameter, so the baseline 3 applies.

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

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

States a specific verb (returns/describes) and resource (what this lake holds: datasets, coverage windows, history modes, freshness) plus the query contract. It is unmistakable against siblings like query_bars or run_sql, which retrieve data rather than describe the lake.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'START HERE' and 'Call it before answering anything factual about A-share data', with a concrete decision rule (use coverage_start/coverage_end to separate 'no such data' from 'did not happen'). It then names each alternative tool and the condition that selects it (resolve_symbol for names, query_bars for prices, query_fundamentals for financials, query_dataset for everything else, run_sql for aggregation).

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

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

Annotations only declare readOnlyHint=true, so the description carries the real behavioral burden and does: prices are stored UNADJUSTED with a concrete failure mode (a split reads as a crash), the `origin` field distinguishes validated lake data from freshly fetched live data that cannot be adjusted or universe-filtered, and incomplete research fails rather than silently defaulting. This is richer behavioral context than the read-only hint alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the unadjusted-price hazard is stated in the first sentence, before the softer dataset and origin details. Nearly every clause carries information, though the dataset enumeration and resampling parenthetical are slightly overstuffed for a single block of prose.

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

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

With no output schema in play, the description compensates by explaining what the response carries (`origin`, its warning, the true total and `truncated` flag) and what the source variants mean. For a 9-parameter analytical tool this is an unusually complete brief.

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

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

Schema coverage is already 100%, so the baseline is 3, and the description adds genuine use-case framing on top ('hfq for return series', 'qfq when levels must match a quote screen', 'all_a for cross-sectional work to drop names that were not tradable that day'). It also surfaces the resampled_from and truncation semantics. It stops short of documenting every parameter, but the marginal value is real.

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

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

Opens with a specific resource and scope ('Daily or intraday price bars') and explicitly distinguishes itself from siblings by naming query_fundamentals, query_dataset, and run_sql as the wrong tools for adjacent tasks. An agent can route to this tool without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use rules for the tricky parameters ('adjust=\'hfq\' for any comparison across time', 'adjust=\'qfq\' when levels must match a quote screen', 'universe=\'all_a\' for cross-sectional work') plus a clear exclusion list pointing at three alternative tools. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description nonetheless adds real behavioral context beyond that: results are paged, the response reports the true total and a truncated flag, and the paging pattern is unsuitable for cross-sectional ranking. It stops short of discussing auth, rate limits, or result freshness, which is why this is a 4 rather than a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core verb and scope, then routing, then pagination behavior — a logical order where most sentences earn their place. The long dataset enumeration is informative but slightly heavy; a pointer to describe_lake alone might have sufficed.

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

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

For a 7-parameter read tool with no output schema, the description covers the essentials an agent needs: what datasets exist, where to find the canonical list, how results are paged, that the response reports a true total and truncated flag, and when to prefer run_sql. Nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, including date formats, the limit default/cap, offset paging, symbol format, and the provenance default — so the schema carries the parameter burden. The description's mentions of 'date window', 'symbol', and 'paged with limit/offset' restate schema content rather than adding syntax or semantics. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Read any other dataset by date window and symbol') and enumerates concrete datasets (fund_flow, margin_trading, dragon_tiger, etc.). It explicitly carves out the sibling tools that handle other data classes (bars → query_bars, financials → query_fundamentals), so an agent can distinguish it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing rules in both directions: use describe_lake for the dataset list and coverage, use query_bars/query_fundamentals for bars and statements, and use run_sql instead of paging when doing cross-sectional ranking. These are concrete when/when-not/alternative statements rather than implied guidance.

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

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

Annotations only declare readOnlyHint=true; the description adds the non-obvious semantics: look-ahead prevention, restated figures returning the then-current vintage, and the warning that all_vintages double-counts a fact in cross-sectional screens. That is exactly the behavioral context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the resource and the required parameter, then trades one sentence each for date choice, siblings, paging, and pit_mode. High information density with no filler or restatement of the schema.

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

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

With no output schema, the description still covers paging/truncation behavior and result semantics, and every parameter is documented either in the schema or here. An agent has everything needed to call it correctly on the first attempt.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real interpretation: why `as_of` is required and which value to choose, and the audit-only intent behind pit_mode='strict'. The rest (items, limit, offset, symbols) is left to the already-complete schema.

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

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

States a specific resource (financial statement items) plus the defining scope: point-in-time with a required `as_of` knowledge cutoff. It explicitly separates itself from query_bars (prices) and query_dataset (valuation ratios), so an agent can pick it without opening other schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use rules for the key decision — pass today's date for a present-day view, the studied date for a historical study, 'never today'. It names the two sibling alternatives by function and restricts pit_mode='strict' to lake-audit use.

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

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

Annotations only declare readOnlyHint=true; the description goes well beyond by disclosing that delisted names are included and flagged with delist_date, that a wrong suffix silently yields an empty result instead of an error, and that multiple rows signal an ambiguous fragment. These are non-obvious behaviors that materially change how an agent should interpret results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, zero padding: example, precondition/consequence, then return shape and ambiguity handling. The most actionable constraint (resolve before querying) is front-loaded.

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

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

With no output schema, the description still covers what comes back (canonical symbol, name, delist_date) and how to interpret multi-row results. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds accepted-form examples and clarifies that the match returns the canonical suffixed symbol for later calls. The `limit` parameter is left to the schema, which documents it thoroughly.

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

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

States a specific verb+resource ('Look up a symbol') and immediately grounds it with concrete examples ('茅台', 'maotai', '600519' → 600519.SH). An agent can distinguish this resolver from sibling query tools (query_bars, run_sql) without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use it ('Do this before any query when the user named a company rather than a code') and why ('a guessed suffix returns an empty result rather than an error'). It also handles the ambiguous-fragment case, instructing the agent to pick by name before querying.

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

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

Beyond readOnlyHint=true, it discloses a hard constraint not visible in annotations: single SELECT only, no writes, DDL, or multiple statements. It also explains the pre-built view semantics (daily_bars_adj columns, daily_bars_qfq window anchoring) and warns to prefer them over manual adj_factors joins.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and constraint, and the alternative-tool routing lands at the end. It is dense with backticked identifiers and multi-clause sentences, but nearly every clause carries actionable information.

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

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

For a single-query tool with no output schema and fully described parameters, the description covers scope, constraints, view semantics, and sibling routing. Nothing critical for a correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the limit default/cap and truncated flag. The description adds view/table-name context implicitly but no syntax or format detail for the sql or limit arguments themselves, so the baseline 3 applies.

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

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

States a specific verb and resource: a read-only DuckDB SELECT executed over every dataset, each exposed as a view under its own name. It also names the sibling tools it is not (query_bars, query_dataset), so an agent can route without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('ranking, aggregation, percentiles and joins across datasets') with a rationale (cheaper than paging rows), plus explicit alternatives for the two adjacent cases: query_bars for one symbol's bars and query_dataset for plain reads.

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