get_graph

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It details the return format thoroughly, explains that semantic_edges are based on cosine similarity, and clarifies that unresolved_links are not edges but dangling references. The warning about the unfiltered response potentially not fitting in context is a valuable behavioral trait. It doesn't explicitly state read-only behavior, but given the focus on retrieval and the lack of any mutation verbs, it's implicitly safe.

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 dense and information-rich, but it is slightly long, covering multiple aspects such as structure, semantics, and usage warnings. It front-loads the core purpose and structural details, which is effective, but the later part about node titles being valid wikilink targets adds context that might be less critical. Overall, it is efficient without being verbose.

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 (multiple edge types, indexing conventions, and scoping options), the description covers most essential details: node format, edge indexing, semantic edge threshold, unresolved links, and scoping recommendations. It lacks some information like whether depth is inclusive or exclusive, but that is handled by the schema. The warning about context limits is crucial for an agent. No output schema exists, so the description must cover return format, which it does thoroughly.

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 input schema already provides 100% description coverage for all six parameters, including their purpose and constraints. The description adds context by explaining how these parameters affect the graph structure (e.g., depth for hop count, min_score for semantic edge threshold) and how nodes reference each other. However, this is marginal value beyond the schema; the description could have delved deeper into parameter interactions, but the baseline of 3 is appropriate given 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 identifies the tool's purpose: to retrieve a knowledge graph with specific node/edge types. It distinguishes itself from siblings by focusing on graph structure rather than individual notes or lists. The explanation of nodes, edges, and semantic_edges is specific and actionable.

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 explicitly states when to use this tool versus alternatives: it recommends scoping with folder_id or root_title+depth when you need only part of the graph, and it warns about the unfiltered full-vault return being too large for context. This guidance is direct and practical, helping the agent choose appropriate parameters.

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