build_kdb

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

With no annotations, the description carries the full burden, and it covers a lot: cache location, cache-hit reuse, LSF queue behavior with no fallback, generation of build.sh, and the VERDI_HOME requirement. It does not mention error behavior or the exact return value, but for a build/caching tool the key side effects and preconditions are disclosed.

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 dense but every sentence earns its place: purpose, when to use, caching behavior, LSF execution semantics, reproducibility script, and environment prerequisite. The most important information is front-loaded in the first two sentences, making it easy for an agent to quickly decide whether to invoke the tool.

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 mutation/build tool with no annotations and no output schema, the description does strong work by covering environment requirements, caching, LSF behavior, and side effects. It stops short of stating what the tool returns on success or failure, which would make it fully self-contained for an agent. Overall, the missing return/error contract is a minor but real gap.

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 100%, so the baseline is 3. The description reinforces the meaning of force_rebuild ('force-refresh') and compile_log ('parsed compile log'), but it does not add substantial parameter-level detail beyond what the schema already provides. It adds context around environment variables and execution mode rather than parameter semantics.

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 first sentence states a specific action and resource: 'Auto-build a Verdi KDB from a parsed compile log using vericom + elabcom.' It immediately differentiates this tool from the analysis/query siblings by focusing on construction of a KDB cache artifact. The use cases (Xcelium, missing KDB, stale cache) further disambiguate its purpose.

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 explicitly says when to use the tool: when the simulator is Xcelium (xrun), the NPI backend reports no KDB, or a stale cached KDB needs refreshing. It also gives behavior-specific guidance for TRACEWEAVE_NPI_EXECUTION=lsf. It does not explicitly name a non-use case or contrast with a sibling alternative, but the 'use this when' phrasing is clear enough.

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