Locate elements in WeChat mini-program pages using selectors, IDs, test IDs, data IDs, or text, returning references for further automation.
在 Page 根作用域通过 selector、id、testId、dataId 或 text 查找元素并返回 opaque ref
| Name | Required | Description | Default |
|---|---|---|---|
| locator | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| code | Yes | ||
| data | Yes | ||
| meta | Yes | ||
| error | Yes | ||
| warnings | Yes | ||
| nextActions | Yes | ||
| observation | Yes | ||
| partialData | Yes | ||
| schemaVersion | Yes |
Changes observed during successful MCP inspections.
v0.7.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It adds useful behavioral detail: lookup is scoped to Page root and returns an opaque ref rather than a value. It does not cover no-match behavior, multi-match indexing, or side effects, but for a read-only find operation this is a moderate gap.
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?
One sentence, front-loaded with scope, then locator kinds, then return type; every phrase carries meaning. No redundancy or filler.
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?
The tool has a single, richly described locator parameter and an output schema, so the description only needs to convey purpose, scope, and return nature, which it does. Minor omissions—alternative guidance and edge-case behavior—do not block correct invocation.
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 for the locator parameter is 0%, and the description compensates by enumerating the five accepted kinds (selector, id, testId, dataId, text). It does not mention variant-specific fields like index, exact, or tagName, though those are described in the input schema, so the addition is partial.
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?
Description names a specific verb ('查找'), object ('元素'), scopes it to 'Page 根作用域', lists five locator strategies, and states the result is an 'opaque ref'. This makes it distinguishable from value-returning siblings like get_value or get_page_snapshot.
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?
It clearly bounds usage to the Page root scope and enumerates the supported locator kinds, so an agent can infer when it applies. It does not explicitly name alternatives or exclusion conditions, but the scope and opaque-ref return type provide enough context to choose it over value-returning tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.