tune_weights

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

Annotations only provide readOnlyHint=false, so the description carries the burden of explaining mutability. It does so by clarifying inspect vs override vs reset modes, and it discloses precedence ('per-dataset overrides win over the global default, which wins over built-ins') and runtime effect ('Honored by search_data at query time'). It lacks an explicit warning about the destructive nature of reset or persistence semantics, but the overview is strong; hence 4.

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?

Despite covering multiple modes, scoping, and a long list of tunable weights, the description stays in one tight paragraph, front-loaded with the core action. Every sentence contributes—modes, scope, runtime effect, differentiation, and tunable list—making it efficient.

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?

The tool has no output schema and only a minimal annotation; the description adequately covers the operation, scope, precedence, and runtime effect. It hints at the inspect result ('effective weights and their source') but doesn't explicitly describe the return structure or persistence of changes, which would make it fully complete; hence 4.

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 baseline is 3. The description adds meaningful usage semantics: the interplay of omit-all, set_weights, reset, and dataset scoping, plus the full list of tunable weights. This goes beyond the schema's per-parameter descriptions, earning a 4.

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 'Inspect, set, or reset the weight vector search_data uses to rank columns', which precisely defines the tool's three modes and its target resource. The explicit differentiation from jcodemunch/jdocmunch ('Unlike... weights are tuned explicitly here') distinguishes it from alternative tuning mechanisms.

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 gives explicit mode instructions: 'Omit all args to inspect', 'Pass set_weights... to override', 'reset=true to clear', and explains scoping with 'dataset (per-dataset overrides win over the global default)'. It also notes the alternative: 'Unlike jcodemunch/jdocmunch, weights are tuned explicitly here'.

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