mcp_engram_search_by_relation

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

Without annotations, the description carries the burden of behavioral disclosure. It mentions traversal and filtering but does not specify traversal depth (single-hop or multi-hop), behavior with cyclic graphs, or whether results include relationship metadata. This is adequate but not comprehensive for a graph traversal tool.

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 two sentences long, front-loaded with the primary action ('Traverse the knowledge graph'), and each sentence earns its place. No extraneous information.

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?

Despite the succinct description, completeness is lacking because there is no output schema and the description does not explain the return format (e.g., list of concept names, full objects, or edges). The agent cannot infer what data to expect, which is critical for a search 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?

The input schema already provides good descriptions for all three parameters (concept, direction, label). The description merely restates that filtering is optional, adding no new semantic meaning beyond what the schema offers. With 100% schema coverage, the baseline is 3.

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 traverses the knowledge graph to find concepts related to a seed concept, with optional filters. The verb 'traverse' and 'find' accurately describe the action, and the resource 'concepts related to a seed concept' distinguishes it from other sibling tools like mcp_engram_read_concept (single concept read) or mcp_engram_query_with_momentum (different approach).

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 implicitly indicates use when needing to find related concepts by relation, but does not explicitly state when to use this tool vs alternatives (e.g., mcp_engram_read_concept for direct reading, or mcp_engram_visualize for visual exploration). No when-not-to-use or exclusion criteria are provided.

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