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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower; the description still adds real behavior: directional scope changes with case_id, absence of a path means no claim, and the underlying algorithm (FalkorDB algo.SPpaths). It does not disclose how max_len/path_count defaults shape results or what a truncated search means.

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?

Front-loaded with what the tool produces, then the case_id branching, then the caveat. Sentences are dense and earn their place, with only the trailing 'FalkorDB features: algo.SPpaths' being an implementation detail of marginal value to an agent choosing a tool.

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?

With no output schema, the description correctly describes the return shape (hop-by-hop paths with transaction ids, amounts, and banks) and the null result case. Combined with read-only annotations, an agent has enough to call it and interpret results; the remaining gap is the effect of max_len and path_count on truncation.

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% across 5 parameters, so the description must compensate. It does explain the semantics of case_id well (consortium search vs. case-graph bidirectional search), and src/dst are self-evident. But max_len and path_count — which directly bound the result — get no explanation of units, bounds, or effect, leaving the most result-shaping params undocumented in both places.

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?

States a specific verb and resource ('shortest money paths from one account to another') plus the exact payload of each hop (transaction ids, amounts, bank of every account). This is clearly separable from siblings like find_rings, account_network, and connected_components, which explore graph structure rather than tracing a directed path between two named accounts.

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 gives a genuine when-to-use rule tied to an argument: without case_id it scans the consortium along outgoing transfers, with case_id it searches that case's graph bidirectionally. 'No path = no claim' is a useful negative-result caveat. It stops short of naming an alternative sibling for the no-case, exploratory case (e.g. account_network), so it is clear context without explicit exclusions.

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