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

Beyond the annotations, the description discloses meaningful privacy behavior: analysis will not inform the counterparty or modify the plan, and research never sends private plans or personal data to search. This adds security and side-effect context that the schema and annotations do not provide. It does not contradict readOnlyHint=false because it only claims no plan modification, not no side effects at all.

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 four short sentences, front-loaded with the most important constraint ('only current user-visible plans'), and every sentence adds meaningful privacy or authorization guidance. There is no filler, though the density of multiple constraints in one sentence slightly reduces skimmability.

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?

This is a complex 11-parameter tool with nested objects and no output schema. The description thoroughly covers privacy and research constraints but omits operational essentials: what the analysis should be based on, how message/selection/context interact, what output the agent should produce, and what expectedRevision/expectedDocumentHash protect against. The agent would need to infer too much.

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 0%, so the description needs to compensate. It does explain useMyProfile and research.industryTopic, but it leaves 9 other parameters (message, planId, context, history, selection, requestId, shareAccessId, expectedRevision, expectedDocumentHash) entirely to their names. Given the complexity of nested objects and versioning fields, this is insufficient.

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 establishes the tool as a private analysis advisor over cooperation plans, with phrases like '只用当前用户可见方案' and '分析不会告知对方或修改方案.' The core action 'analyze' is implied by the name/title and the repeated use of '分析,' and the resource is clear. However, it does not explicitly differentiate itself from siblings such as get_cooperation_analysis or get_cooperation_plan.

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 gives useful conditional rules: useMyProfile requires user authorization, and research must be explicitly requested with a de-identified public industry topic. It also limits the tool to plans visible to the current user. It lacks an explicit 'use X instead' comparison with sibling tools, but the preconditions and exclusions are clear enough for an agent to decide when this tool is appropriate.

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