falkordb_query

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

Annotations are non-informative (readOnlyHint false, destructiveHint false), so the description must carry behavioral disclosure. It does not clarify that executing arbitrary Cypher queries can modify data, nor does it mention transaction or side-effect behavior. This is a significant gap for a tool that can perform destructive operations.

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 clear sections (intro, args, returns, examples, errors) and is reasonably concise. Some repetition of parameter details from the schema could be trimmed, but overall it is efficiently organized and front-loaded.

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 tool's complexity and the presence of an output schema (not shown), the description adequately covers input parameters, error types, and usage examples. It lacks details on transaction handling or write behavior, but the core selection and invocation context is sufficiently addressed.

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?

The description enriches the input schema by listing each parameter (query, graph, params, response_format) with examples and constraints, adding practical context beyond the schema's descriptions. However, some schema properties like 'graph' being required are not explicitly repeated, though implied.

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 executes Cypher queries against FalkorDB, specifying the main action and resource. However, it does not explicitly differentiate from sibling tools like falkordb_get_nodes or falkordb_list_graphs, which could cause confusion about when to use this general query tool vs specialized ones.

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 provides examples and notes on parameterized queries, which imply usage scenarios but do not offer explicit when-to-use or when-not-to-use guidance. There is no mention of alternatives or exclusions, leaving the agent to infer context from the purpose alone.

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