Link Entities

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

The description adds useful operational context beyond the annotations: it costs $0.10 and requires an API key, and it clarifies that the output is graph-structured rather than prose. It does not disclose whether duplicate links are ignored, whether existing links are replaced, or whether entity IDs must already exist, but the annotations already cover read-only and destructive intent.

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 a single compact sentence with no filler, and the primary purpose is front-loaded. The cost and API-key requirement are placed at the end, and each segment earns its place, though the arrow notation is dense.

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?

The required parameters are represented in the arrow notation, and the idempotency keys are documented in the schema, with an output schema available for return values. However, with eight parameters and no enums, the description still leaves link_type semantics, notes, and ID sourcing unexplained, making it only minimally complete.

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 only 25%, so the description needed to compensate for required parameters like from_type, to_type, link_type, and notes. The arrow notation gives clues about valid endpoint type values, but it does not explain ID formats, the meaning of link_type, or how notes should be used.

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 names a specific verb ('Link') and resource ('entities'), and the arrow notation 'Trip→Stay→Place / Event→Person' scopes the operation to particular graph relationships. It is clear enough to distinguish from sibling tools like link_people and link_inventory_person, though it does not fully define what a 'Stay' is or enumerate every valid endpoint combination.

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 allowed edge pattern implies when this tool should be used, and the 'graph, not prose' note suggests the intended output model. However, there is no explicit when-not-to-use guidance or alternative routing to sibling tools like link_people or unlink_people, so an agent must infer selection.

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