project_code_search

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals a notable side effect: 'Auto-indexes the project on first search if no index exists.' It also describes the semantic search mechanism and per-project vector DBs. Missing details like rate limits or response behavior are less critical here, but the auto-indexing disclosure is valuable and non-obvious.

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 and efficient: a one-sentence purpose, two clarifying sentences, then a clean Args block. Every sentence adds value, and the most important facts are front-loaded. No filler or redundant phrasing.

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?

For a four-parameter search tool with an output schema, the description covers purpose, behavior, parameter semantics, and search scope. Auto-indexing behavior is disclosed, and the output schema handles return-value documentation. The only slight gap is lack of explicit sibling differentiation, but that does not make the description incomplete for invoking the tool correctly.

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%, so the description must compensate fully—and it does. Every parameter is explained with examples (e.g., query examples, project paths, n_results default, chunk_type filter values). The inclusion of 'Omit to search all' for project adds crucial semantic meaning not inferable from the schema alone.

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 clear, specific verb and resource: 'Semantic search over project source code and documentation.' It further specifies per-project FalkorDB vector DBs, which helps distinguish it from generic search. However, it does not explicitly contrast itself with sibling tools like source_search or kb_search, leaving some differentiation to inference.

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 clear use-case guidance: 'Useful for finding code patterns, functions, classes, and docs across projects.' This tells an agent when to invoke the tool. It does not name alternatives or state when not to use it, but the context is sufficient for most selection decisions.

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