lark_oauth_revoke

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it's a destructive operation (deleting tokens), requires a confirmation parameter to prevent accidents, and has downstream effects ('之后该用户的 feishu_* 工具会再次要求授权' meaning 'afterwards, the user's feishu_* tools will require re-authorization'). This adds valuable context beyond basic parameters.

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 front-loaded with the core action and requirements in two concise sentences. Every sentence earns its place: the first states the purpose and mandatory parameter, the second explains the consequence. There is no wasted text, making it highly efficient.

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 (destructive OAuth operation with 2 parameters), no annotations, and no output schema, the description is largely complete. It covers purpose, usage, behavioral effects, and parameter intent. However, it lacks details on error cases, response format, or permissions required, leaving minor gaps for a mutation tool.

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 'confirm' has a description). The description compensates by explaining the purpose of 'confirm' ('调用者必须传 confirm=true' and its role in preventing accidental revocation) and implies 'open_id' identifies the user, though it doesn't detail format or constraints. This adds meaningful semantics beyond the schema's minimal coverage.

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 specific action ('删除' meaning 'delete' or 'revoke') and the resource ('已存储 user_access_token' meaning 'stored user_access_token'), with explicit mention of the user scope ('指定用户的' meaning 'specified user's'). It distinguishes from siblings like lark_oauth_start or lark_oauth_status by focusing on token revocation rather than initiation or status checking.

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: to revoke a user's access token, with the explicit requirement '调用者必须传 confirm=true' (caller must pass confirm=true). However, it does not specify when NOT to use it or name alternatives among siblings (e.g., lark_oauth_status for checking token validity), leaving some guidance gaps.

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