graph_detectCycles

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

Annotations indicate readOnlyHint=true and idempotentHint=true. The description adds significant context: 'Pure-Python implementation — no stored procedure required. Issues a single SQL SELECT... WCC partitioning followed by iterative DFS cycle detection entirely in the MCP server process.' This details internal behavior beyond the annotations.

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 bullet points for use cases and arguments, and a clear output section. It is reasonably concise given the detail needed, though minor redundancy exists (e.g., repeating 'edge_repository' explanation).

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 has three parameters and no output schema, the description provides complete coverage: purpose, implementation details, parameter semantics, and a full output schema description with fields and structure. It leaves no major gaps for an agent to misinterpret.

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%, requiring the description to fully explain parameters. It does so thoroughly: container_pattern with examples ('DFJ%', '%WBC%,%StGeo%'), exclude_objects with default, and edge_repository with an example and reference to graph_edgeContractDDL. Each parameter's purpose and format are clearly stated.

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 explicitly states 'Detect circular dependencies (cycles) in the dependency graph,' specifying the verb 'detect' and the resource 'dependency graph.' It distinguishes from sibling tools like graph_connectedComponents and graph_bfsLevels, which serve different graph analysis purposes.

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 lists multiple use cases (validating graph integrity, finding circular references, identifying stub-then-replace patterns, debugging topological sort hangs, pre-deployment checks) and explains arguments with examples. It lacks explicit exclusion criteria or alternative tool references, but the provided context is clear.

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