connect_people

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Never guesses ambiguous names,' which is a constraint rather than describing behavior like whether connections are bidirectional, whether duplicate relationships are possible, whether existing relationships get overwritten, or the effects of the optional note/strength fields. For a mutation tool creating relationships in what appears to be a knowledge graph, this is a significant transparency gap.

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 appropriately short at two sentences. The first sentence is front-loaded and clear. However, it's borderline under-specified rather than genuinely concise—the second sentence adds only a constraint. Given the tool's complexity (5 parameters, relationship semantics), slightly more length could be justified.

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?

There is an output schema, so return-value documentation isn't required. However, with 0% schema coverage, 5 parameters (3 required), and no annotations, the description is incomplete. It doesn't document valid 'kind' values, the strength semantics, or what a successful connection does to the graph. It's minimally functional but leaves important behavioral and parameter gaps for a tool with this complexity.

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%, so the description must compensate for undocumented parameters. It doesn't explain what 'kind' values are valid (relationship types), what strength means numerically, or what note is for. Neither the schema (bare titles like 'Kind', 'Person A', 'Strength') nor the description provide meaningful semantics for 3 of the 5 parameters. The description adds no parameter-level meaning beyond the 'ambiguous names' constraint.

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 clear purpose: 'Create a relationship between two existing people.' This uses a specific verb (create) with a clear resource (relationship between people). It distinguishes from siblings—search_people, get_person, remember_person all deal with individual people rather than relationships, while connect_people specifically targets the connection. However, it doesn't name the sibling relationships explicitly.

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 includes a partial usage guideline: 'Never guesses ambiguous names' implies the tool requires existing/unambiguous person references. However, it doesn't explain when to use this vs. record_interaction or add_fact (which could also capture relationships), nor does it specify prerequisites like whether people must already exist in the graph. The guidance is implied rather than explicit.

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