create_relation

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

No annotations are provided, so the description carries full behavioral disclosure burden. The description indicates a write/mutation operation ('作成') but doesn't disclose whether source and target entries must already exist, whether relationships can be duplicated, whether both IDs must reference different entries, or what happens on failure. With no annotations, this is under-specified for a mutation tool.

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 in Japanese, which is efficient. However, given the semantic complexity of the relation_type enum (8 distinct relationship types) and the directionality semantics of source vs target, the description under-uses its space. It's appropriately short but could front-load more value about the relation_type semantics.

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?

This is a semantically rich tool with 3 enums and directionality concepts, yet no annotations and no output schema exist. The description provides only two examples and doesn't explain directionality conventions, whether relations are bidirectional, or the meaning/semantics of each of the 8 relation_type values. For a tool with this complexity, the description is incomplete and relies too heavily on parameter labels.

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 coverage is 100% with descriptive parameter labels (source_type, target_type, relation_type, source_id, target_id, description), and enums for the three type parameters give clear allowed values. The description adds the semantic meaning that relation_type expresses causality/demonstration relationships through the examples. However, the description doesn't clarify the exact meaning of each relation_type enum value or how source/target directionality is interpreted, leaving this to the enum labels.

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 creates relationships between entries, with concrete examples like 'エピソードがスキルを実証' (episode demonstrates skill) and '経歴がプロジェクトに繋がった' (career led to project). This distinguishes it from the sibling tools create_*/delete_relation/get_relations. However, it doesn't explicitly name the key verbs beyond '作成' (create), making it slightly less specific than ideal.

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 the tool is used to create inter-entry relationships, an action distinct from the many create_* CRUD tools. However, it gives no explicit guidance on when to use this vs alternatives, no prerequisites (e.g., that referenced entries must exist), and no instructions on which relation_type enum values are appropriate in which contexts. The usage context is inferred rather than stated.

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