extract_graph_v1

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

With no annotations, the description carries full burden. It discloses parallel processing, real-time progress, and the dry_run parameter for preview. However, it does not mention potential side effects (e.g., overwriting data), permissions required, or error behavior. The description provides moderate transparency but has gaps.

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 relatively concise, with a two-sentence summary followed by a structured Args list. However, the Args list repeats defaults already present in the schema, slightly reducing conciseness. The front-loading of the purpose is effective.

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 presence of an output schema (not shown), the description does not need to detail return values. It covers key aspects: action, target, parameters, concurrency, and dry-run mode. Missing details like idempotency or error handling are acceptable for a tool of this complexity.

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 must compensate. The Args list explains each parameter (e.g., doc_id: 文档 ID, mode: 模式). While brief, it adds meaning beyond the schema, especially for parameters like dry_run and concurrency. This compensates well for the lack of schema descriptions.

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: extracting entities, relations, and conclusions from document chunks and writing to the GraphRAG table. It mentions async parallel processing and real-time progress reporting, which distinguishes it from related tools like extract_graph_missing.

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?

No explicit guidance on when to use this tool versus alternatives (e.g., extract_graph_missing). The description does not provide when-not conditions or context for selecting this tool over siblings, leaving the agent to infer usage from the purpose.

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