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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful algorithmic context: it 'queries the edge repository,' identifies 'objects that appear as sources but never as targets,' and applies exclude/object-type filters before returning results. It does not disclose potential performance costs or return-size limits, but the read-only and idempotent annotations lower the burden here.

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-organized with clear sections: overview, use cases, parameter details, examples, and technical implementation. The repeated emphasis on the string-type container_pattern is justified by the likely array-passing mistake, though some 'Technical Implementation' points restate earlier content.

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 is thorough for a 5-parameter tool with no output schema: it defines every parameter, gives positive and negative examples, and describes return format options. It is not fully complete because of the edge_repository requirement contradiction and the extraneous conn argument in examples, which could mislead an agent despite the otherwise rich guidance.

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 0% schema description coverage, the description compensates extensively: it documents wildcards, CSV formatting, string-vs-array pitfalls, whitespace trimming, defaults, and examples for every parameter. However, it says edge_repository is a 'Required parameter — no default,' while the schema marks it optional with a default of ''; the example calls also include a 'conn=connection' argument that is not in the schema and would violate additionalProperties:false.

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: 'Find root objects (objects with no upstream dependencies) in specified containers.' It then explains what root objects are and why they matter, which clearly differentiates this from lineage-tracing and graph-analysis siblings like graph_traceLineage and graph_bfsLevels.

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 'Use this for' section gives explicit scenarios such as 'Finding starting points for downstream impact analysis' and 'Identifying source tables and base objects in data pipelines.' It does not name alternative sibling tools or provide negative guidance ('do not use when...'), so it stops short of full when-to-use-versus-alternatives clarity.

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