sgraph_cypher_query

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It documents the read-only constraint, what the graph mapping looks like, how relationships are represented, the performance trade-offs of include_hierarchy, that results are returned as a JSON array, and that initial indexing may take seconds on large models. This is unusually transparent for a tool description.

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 long but well-structured and front-loaded. The first sentence states the core behavior, followed by usage guidance, graph schema information, examples, performance notes, and return format. Every section adds value needed to use the tool correctly; the examples are illustrative rather than redundant. This is appropriate density for a complex query tool, not padding.

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 tool is complex, has no output schema, and has no annotations, yet the description covers all essential invocation concerns: what the model is, how to write queries, relationship types, property names, hierarchy behavior, performance expectations, return format, and read-only constraints. An agent has enough information to construct and run a correct openCypher query without external documentation.

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 top-level schema reports 0% description coverage, so the description must compensate. It does so substantially by explaining the query language, node/relationship mapping, property conventions, and hierarchy behavior. It does not explicitly explain the `limit` safety parameter or `model_id` optionality, but the schema itself describes those fields, and the examples demonstrate how to write valid queries. This is strong compensation but not exhaustive.

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 opens with a specific verb and resource: 'Run an openCypher query against the loaded model.' It goes beyond a tautology by explaining what the tool expresses — multi-hop paths, aggregation, complex filtering — and explicitly differentiates itself from other tools by noting these are queries 'the other tools can't express.' The mapping to a labeled property graph and example queries make the purpose unmistakable.

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 explicitly states when to use this tool: 'Use this tool for complex graph queries that the other tools can't express,' followed by concrete categories. It also gives exclusions, telling users that CREATE/DELETE/SET are not supported and that include_hierarchy=false is the recommended default unless parent-child traversal is needed. This gives the agent clear selection criteria relative to sibling tools.

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