sgraph_search_elements

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

With no annotations provided, the description carries the behavioral burden. It usefully discloses that scope defaults to the server default when available, that model_id can be omitted to use an auto-loaded model, and that the response is JSON with a match count and element list. It does not explicitly mention truncation or result limits, but the search semantics are otherwise transparent.

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 a one-sentence summary, a focused 'When to use' list, a compact parameter breakdown, and a clear return line. There is no fluff, and the most important scoping information is 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 no output schema and no annotations, the description should be fairly self-sufficient. It covers purpose, usage, and core parameter behavior, but it misses the max_results parameter and does not explain that results may be truncated by that limit, which is relevant for the 'find all implementations' use case. The return value is described only as a count and element list, with no detail about element shape.

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 adds helpful semantics for query, scope_path, element_types, and model_id, going beyond bare schema labels with wildcard/regex/substring examples. However, it omits max_results entirely, and it lists "dir" as a valid element_types value while the schema says "directory," creating a potential incorrect invocation.

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 code elements by name pattern." It clearly distinguishes this tool from generic text search by saying "Use instead of grep for precise symbol lookup," and the positioning relative to dependency queries is explicit in the usage bullets.

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 'When to use' section gives three concrete, actionable scenarios: locating a symbol by name, finding pattern matches like *Service*, and resolving a symbol before querying dependencies. It provides clear context but does not explicitly state when not to use it or name sibling tool alternatives, so it falls just short of a 5.

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