Rebuild Data Flow

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

With no annotations, the description must fully disclose behavioral traits. It mentions rebuilding from two sources and optionally syncing module files, but omits critical information: whether the operation is destructive (overwrites existing dataFlow), reversible, or idempotent. It also fails to mention authorization needs or error states. The 'pruneOrphans' parameter hints at deletion, but the description does not address this directly. This lack of transparency could lead to risky invocations.

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 exceptionally concise—two sentences totaling about 20 words. The first sentence states the core action and sources, and the second provides a usage recommendation. Every word is purposeful, with no redundancy or filler. The structure is front-loaded with the essential action, making it easy for an agent to quickly grasp the tool's purpose.

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 (4 parameters, multiple source options, potential for side effects like pruning orphans), the description is incomplete. It does not address prerequisites (e.g., project must exist), safety implications (e.g., is it safe to run multiple times?), or fallback behavior. The presence of an output schema reduces the need to explain return values, but the lack of behavioral and contextual details leaves significant gaps for an AI agent to safely and correctly use this 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?

Since the input schema has 100% coverage with descriptions for all 4 parameters, the description adds minimal extra value beyond repeating the schema's purpose. The description's mention of 'optionally syncs module files' maps to the 'syncInverse' parameter but is slightly vague. Overall, the description does not significantly enhance understanding of parameters beyond what the schema already provides, meeting the baseline expectation for high schema 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 verb 'rebuilds' and the resource 'dataFlow for all modules', specifying two source types (module file dependencies or dependsOn edges) and the recomputation of providesTo. It also advises using this tool instead of editing architecture.json directly. However, it does not explicitly differentiate from sibling tools like 'set-module-data-flow' or 'refactor-architecture', leaving some ambiguity about when to prefer this over alternatives.

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 one usage guideline: 'Use instead of editing architecture.json directly', which tells when not to use manual editing. It does not specify when to use this tool versus other sibling tools (e.g., for individual module updates use set-module-data-flow), nor does it mention prerequisites or conditions (e.g., project exists). The guidance is implied but not explicit enough for confident selection.

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