get_cross_repo_references

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

With no annotations, the description carries full burden. It discloses key behaviors: adding consumer roots as workspace folders, waiting for indexing, calling get_references, and partitioning results by repo. It also specifies the return structure (library_references, consumer_references, warnings). However, it omits side effects like whether roots are removed after, permissions needed, or potential delays.

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 relatively concise (three sentences) with the main purpose front-loaded. It includes necessary behavioral details without excessive verbosity. Minor redundancy exists (e.g., 'partitions results by repo' and then listing the partitions), but overall it's well-structured.

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's complexity (cross-repo search, indexing, partitioning) and no output schema, the description provides a basic outline but lacks details such as error handling, limitations (e.g., number of roots), prerequisites (e.g., LSP running), and behavior when consumer_roots is null. The return types are explained, but completeness is only moderate.

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 input schema has 5 parameters with 0% coverage in the description. The description does not explain any parameter's meaning, format, or constraints. For example, it doesn't mention that 'line' and 'column' are 0-based or what 'language_id' refers to. The schema's property names are self-documenting but insufficient for complex tools. The description should compensate but fails.

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 clearly states the function: 'Find all references to a library symbol across one or more consumer repositories.' This specific verb-resource combination distinguishes it from siblings like get_references, which is limited to a single repo. The description also outlines the process (adding consumer roots, waiting for indexing, partitioning results), reinforcing purpose clarity.

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 provides explicit context for when to use this tool: 'Use before changing a shared library API to find all downstream callers.' This is helpful, but it does not explicitly state when not to use it or provide alternative tools (e.g., fallback to get_references for single-repo references). The guidance is present but not exhaustive.

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