find_connections

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

With no annotations, the description carries the full burden of behavioral disclosure. It does describe the BFS algorithm and the return shape (list of paths with facts and entities), which is helpful. However, it does not explicitly state that the operation is read-only, nor does it mention performance implications or error behavior (e.g., empty results). It provides some transparency but not comprehensive context.

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 well-structured with a concise summary first, then an Args section and Returns section. Each sentence earns its place, covering essential details without fluff. It is appropriately sized for a tool with six parameters and effectively front-loads the core purpose.

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 description covers all parameters and the return format, which is sufficient for an agent to invoke the tool correctly. An output schema exists (though not shown), and the description independently explains the output structure. Minor gaps include not specifying what happens when no path is found or error conditions, but for a read-only graph traversal, this is likely acceptable. Overall, it is complete for the tool's 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?

With schema description coverage at 0%, the description must fully explain parameters. It does this thoroughly: it lists each parameter, its optionality, defaults, and constraints (e.g., max_depth range 1-10, limit range 1-100). It also clarifies the special behavior of target_entity being optional and what happens when it is None (returns all reachable entities). This completely compensates for the schema's lack of descriptions.

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's function: 'Find connections between entities using BFS graph traversal.' It specifies the verb and resource, and elaborates with 'Discovers how entities are related through chains of facts.' This distinguishes it from most sibling tools that deal with facts, notes, or tags, though it does not explicitly differentiate from the similar 'get_neighbors' tool. The purpose is unambiguous.

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 lacks any explicit guidance on when to use this tool versus alternatives. It does not mention when to prefer find_connections over get_neighbors or search_facts, nor does it state conditions where it is inappropriate. The reader must infer its use case from the purpose alone, providing no routing to or away from sibling tools.

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