diagram_link

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

No annotations are provided, so the description carries the full behavioral burden. It does add the useful reciprocal-visibility fact (get_memory on the linked memory reports referencing diagrams), but it never explains what the `delete` flag does, whether re-linking the same node_key overwrites or duplicates, or what permissions are required for this mutation.

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?

Purpose is front-loaded in the first line, but the middle paragraph ('What turns a diagram into an index of its domain...') is abstract rationale rather than operational information and dilutes an otherwise compact description. It is not bloated, but it spends words on philosophy instead of on the undocumented delete/relation_type parameters.

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?

With no annotations, no output schema, and 0% schema description coverage, the description is the only source of behavioral truth, and it leaves the destructive `delete` flag, the relation_type vocabulary, and overwrite/permission behavior unaddressed. It covers the conceptual model well but not enough for an agent to call a 5-parameter mutation tool safely.

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?

Schema description coverage is 0% across 5 parameters, and the description supplies no parameter-level detail beyond an implicit mapping of 'step' to node_key and 'another memory' to target_uid. `delete` (a destructive toggle) and `relation_type` (with its 'explains' default) are completely undocumented anywhere the agent can see.

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?

States a specific verb+resource: 'Attach another memory to one specific step of a diagram.' The second sentence clarifies the granularity (per-step, not per-diagram) and explicitly routes whole-diagram links to the sibling link_memories(), so an agent can distinguish it from that tool without reading either schema.

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?

Explicitly names the alternative ('for an edge to the diagram as a whole use link_memories() instead') and the condition that selects it, which is exactly the kind of routing guidance agents need. It stops short of any prerequisites, ordering constraints, or guidance on when NOT to link a given memory.

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