knowledge_viz

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

Annotations only provide destructiveHint: false, and the description adds that it writes two files and specifies their intended use (browser and Obsidian). This gives some context about output artifacts. However, it does not disclose potential side effects such as file overwriting, required directory, or whether it can be called repeatedly. The description relies on the annotation for safety but doesn't add much beyond what the annotation already implies (non-destructive). The note about 'same edges as FTS index' adds content context but not behavioral detail.

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 a single, efficient sentence that front-loads the primary action (writing two files) and includes the key detail about content equivalence to the FTS index. There is no redundant phrasing or filler. Every element earns its place, making it highly concise and well-structured.

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?

For a simple tool with one optional parameter and no output schema, the description covers the outputs and content source. However, it omits the output location (e.g., project root vs. current directory) and does not explain how the 'project' parameter influences the generated files. It also does not position the tool among its many siblings. These gaps mean an agent might not fully understand when and how to use it correctly, though the low complexity keeps the deficiency from being severe.

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?

The schema has 100% coverage for the single parameter 'project', with a description stating it is auto-detected if omitted. The tool description does not add any further detail about how the parameter affects the output or its format. Since the schema already documents the parameter, the description adds no additional value, matching the baseline expectation for high coverage situations.

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: it writes two specific output files (knowledge-graph.html and knowledge-graph.canvas) and relates the content to the FTS index. It is not a tautology and uses specific verbs and resources. However, it does not explicitly differentiate from sibling visualization tools like graph_related or qa_viz, relying instead on the unique output filenames to signal distinction.

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?

There is no guidance on when to use this tool versus the siblings. It does not mention exclusions, alternatives, or appropriate contexts. An agent is left to infer that this tool is for generating a specific visualization, but it lacks any 'instead of X' or 'use this when Y' information. This is a significant gap given the large sibling set.

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