memory_graph_relate

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 does this thoroughly: explains that entities auto-create and resolve through aliases, re-assertion bumps confidence, separator variants normalize, and unknown relations are rejected with suggestions. These are significant side effects and error behaviors that are not apparent from the schema alone.

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 well-structured, with three distinct parts: purpose and example, behavioral details, and registry/error handling. Each sentence contributes useful information, though it is longer than strictly necessary. The inclusion of the return format at the end is helpful without being redundant.

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 graph mutation tool with no annotations and 0% schema parameter coverage, this description covers the essential operational context: relation constraints, side effects, error handling, and return values. It misses explicit explanations of optional parameters and the exact content of `warnings`, but overall provides enough information for an agent to use the tool correctly. The presence of a textual output schema reduces the need to describe return values further.

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 description coverage is 0%, so the description must compensate. It explains the core parameters (src, relation, dst) via the example `(web-app, runs-on, host-1)` and the relation registry, and mentions `confidence` in the context of bumping confidence. However, it does not clarify `origin`, `src_type`, `dst_type`, or how the `confidence` parameter affects initial assertion, leaving a gap for these optional fields.

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 function: "Assert a typed relation between two entities" with a concrete example. It distinguishes itself from related tools by mentioning the closed relation registry and the alternative `memory_relation_define` for growing vocabulary, making its role unambiguous.

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 useful guidance on when to use this tool: it handles relations from a closed registry, offers fallbacks for unknown relation names, and directs users to `memory_relation_define` for new relation types. However, it doesn't explicitly compare against graph-related siblings like `memory_graph_unrelate` or `memory_graph`, so the usage context is clear but not fully exhaustive.

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