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

Annotations already signal readOnlyHint=false, idempotentHint=true, and openWorldHint=true, and the description enriches all of them: it reveals this is a slow, paid full LLM recomputation, that duplicate submits are deduped with deduped=true, that the description is stored as declaredContext and pins the chain position, that profile.source stays 'inferred' even on success, and that the operation is externally visible in other users' chain views. There is no contradiction with annotations.

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 long, but every major block earns its place: when-to-use, chained follow-up tools, describe-writing rule, and a pitfalls section covering cost, dedupe, source field, and failure branches. Bold headers and bullets make it navigable, and the front-loaded when-to-use section is exactly where an agent needs it. The app-comparison sentence is slightly redundant, keeping it one point below perfect.

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 full burden of explaining behavior. It covers success flow and verification via get_chain_anchor, four named failure branches with concrete follow-ups, cost/latency warning, idempotent dedupe behavior, and external side effects. For a complex LLM-backed write with no output schema, this is complete.

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 already documents all three params at 100% coverage, and the description still adds real value: it defines the describe formula ('给谁做什么、用什么做、做完交付什么'), forbids fabricating undeclared upstream/downstream, clarifies subjectType/subjectId defaults (user when omitted), and requires product ownership via get_my_products. This goes well beyond the 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 action: take the user's free-text description of what they do, submit it, and let the LLM infer a chain position and place them into the chain network. It explicitly identifies itself as the platform's only free-text-write entry point and distinguishes the default self-scope versus product-scope, so it is not confused with siblings like set_my_role_profile or get_my_positioning.

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?

Leads with an explicit 'when to use' block: right after the user says in conversation what they are doing, the agent should compose a describe and submit; it contrasts this with the manual App flow. It gives the follow-up workflow (get_chain_anchor → get_creator → start_conversation), the product-subject prerequisite (get_my_products first), and explicit don'ts: don't invent relations, don't retry on position_unclear or position_relations_unclear. This is exemplary routing guidance.

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