lark_oauth_complete

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

With no annotations provided, the description carries the full burden and does well. It discloses key behavioral traits: it's a polling operation that blocks until timeout, automatically persists tokens on success, and returns open_id. It also mentions the device_code source from lark_oauth_start. However, it doesn't detail error handling, rate limits, or what happens on failure beyond timeout.

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?

The description is concise and front-loaded: the first sentence states the core purpose, and subsequent sentences add necessary context about persistence and parameter source. Every sentence earns its place with no wasted words, and the structure is logical for a tool description.

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?

Given the tool's complexity (OAuth polling with persistence) and no annotations or output schema, the description is moderately complete. It covers the purpose, usage flow, and key behaviors, but lacks details on error responses, what '超时' (timeout) specifically entails, or the format of returned open_id. For a tool with no structured output, more context on return values would be helpful.

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 50% (only poll_timeout_sec has a description). The description adds value by explaining device_code comes from lark_oauth_start, which clarifies its semantics beyond the schema's minLength constraint. For poll_timeout_sec, the schema already describes it well, so the description doesn't add much. Baseline 3 is appropriate as the description partially compensates for the coverage gap.

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?

The description clearly states the tool's purpose: '轮询 Device Flow 的 token 端点,直到用户在浏览器完成授权或超时' (poll the Device Flow token endpoint until user completes authorization or timeout). It specifies the verb (poll) and resource (token endpoint), though it doesn't explicitly differentiate from sibling tools like lark_oauth_start or lark_oauth_status beyond mentioning the device_code source.

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?

The description provides clear context for when to use this tool: after lark_oauth_start returns a device_code, to poll until authorization completes. It mentions '成功后自动持久化 user_access_token 并返回 open_id' (upon success, automatically persists user_access_token and returns open_id), which helps understand the outcome. However, it doesn't explicitly state when not to use it or compare with alternatives like lark_oauth_status.

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