gograph_tests

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

Annotations already convey a read-only, idempotent, non-destructive safety profile, so the bar for extra credit is lower — and the description clears it substantially: it documents server-side freshness checking/refresh behavior, type-resolution for compiling test packages, bounded CHA-possible evidence for interface dispatch, and the typed_partial result encoding for broken test packages. These are valuable behavioral details that neither schema nor annotations convey.

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 longer than average, but it is deliberately sectioned (WHEN/NOT/RETURNS) and each block adds non-redundant information. The first sentence fully characterizes the tool before introducing alternatives, so the content earns its length even if some clauses could be tightened.

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?

Despite having no output schema, the RETURNS block explicitly describes the returned shape (test function names, targets, file locations), the no-symbol mode, and the empty result case. Edge cases such as non-compiling test packages and the freshness-refresh behavior are covered — the description is fully sufficient for correct invocation.

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 coverage is 100%, so the schema already documents the single optional `symbol` parameter. The description goes one step beyond by explaining the semantics of the missing parameter — omitting it returns all test edges — and by tying the symbol matching to static attribution behavior (exact IDs for direct selectors, CHA-possible evidence for interface dispatch). That adds real meaning beyond the schema baseline.

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 test functions in *_test.go files that statically exercise a named symbol' and immediately distinguishes the two invocation modes (symbol given vs. omitted). It differentiates from siblings like gograph_callers and gograph_fixtures by the test-target niche and the explicit fallback behavior.

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?

WHEN TO USE and NOT TO USE bullets state explicitly the circumstances for calling this tool ('Before editing a function — check what tests are statically attributed') and name the alternatives (gograph_fixtures for test helpers, `go test` and coverage evidence for proving runtime coverage). The exclusion is concrete, so an agent does not have to infer selection criteria.

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