graph

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

The description discloses some behaviors: auto_relate defaults to dry_run (preview) unless dry_run=False, and record_link requires specific parameters. However, it does not fully explain side effects or states for other actions (e.g., whether 'relate' or 'link' are destructive or idempotent). Annotations provide minimal help (readOnlyHint=false but no further detail).

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 relatively long but well-organized with sections for actions and args. It could be more concise by removing redundant phrasing (e.g., '(legacy)' repeated). The front-loaded summary helps, but the overall density may overwhelm agents.

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?

Given the complexity (many actions, 19 parameters), the description covers the overall purpose and lists actions. It hints at per-action parameter requirements (e.g., record_link needs source_rid, target_rid). However, it does not fully map required parameters per action, leaving ambiguity. The presence of an output schema mitigates return value questions.

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?

With 0% schema description coverage, the description must compensate. It provides some parameter explanations (e.g., dry_run for auto_relate, direction for linked_records), but legacy args (entity, relationship, weight) are only listed without meaning. The description adds value but is incomplete for a 19-parameter tool.

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 'Knowledge graph operations' and enumerates specific actions like entity relationships, memory↔entity links, record-to-record links, etc. It distinguishes itself from siblings by focusing on graph relationships, but does not explicitly differentiate from similar tools like memory or recall. The verb+resource are clear.

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?

No explicit guidance on when to use this tool versus siblings (e.g., memory, recall, remember). The description lists actions but does not provide scenarios or contextual cues for choosing this tool over alternative tools.

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