connect

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

With no annotations, the description carries the full burden. It discloses that an existing connection is reinforced and its decay clock resets, which is a key behavioral trait. It also provides rel examples for context. However, it does not mention prerequisites (e.g., nodes existing) or what happens to weight during reinforcement, which would be useful but not critical.

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, front-loaded with the core action. The reinforcement behavior is stated immediately, and rel examples follow. There is no filler or redundancy, making it highly efficient.

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 4-parameter mutation tool with no output schema, the description covers the essential purpose and reinforcement behavior, but leaves weight unexplained and does not mention requirements (e.g., existing nodes) or error conditions. This is adequate for a minimal viable definition but has clear gaps that an agent might need filled.

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 no descriptions (0% coverage), so the description must add meaning. It explains src and dst as nodes, and gives rel examples, but says nothing about weight. This partial coverage leaves weight's purpose ambiguous. The description adds some value but does not fully compensate for the schema gap.

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 states a specific action ('Create a connection from node src to node dst') with a clear verb and resource, and further clarifies the reinforcement behavior on existing connections. This distinctly separates it from siblings like remember (which likely deals with nodes) and reinforce (which may target nodes or other resources).

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 implies when to use this tool (to create or reinforce connections), and gives rel examples for typical use cases. However, it does not explicitly compare with siblings such as reinforce or recall, nor does it state when not to use it. The guidance is implicit rather than direct.

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