set_keyword

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

Annotations only give the safety profile (readOnly=false, destructive=false, openWorld=false); the description adds substantial behavior: in-place line replacement with comments/layout preserved, append-at-end for missing keywords, refusal of multiline values, and the returned lint result plus server.changed fields and follow-up smoke_test step.

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?

Front-loaded core action in the first sentence, then prerequisites, then parameter notes, then return/next-step behavior. Multi-paragraph length is justified by real content, though the return-value paragraph could be tightened slightly.

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?

No output schema exists, so the description carries the return contract (lint_control_file result, server.changed with keyword/old/new) and the next step (check server.status, re-run smoke_test). It also covers the main failure mode (multiline value) and the redirect to make_control_file.

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 0% and there are no enums, so the description must carry parameter meaning: it explains that keyword is validated against the manual's list and gives concrete value examples ('200000' for nsample, 'invgamma 3 0.002' for thetaprior). The ctl parameter, however, is never explicitly described beyond being 'a control file'.

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?

States a specific verb+resource: 'Change one keyword in a control file, then lint the file again.' It clearly distinguishes itself from the file-creating/upgrading siblings by scoping to edits of existing control files.

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?

Explicit when-to-use ('Use this for every edit to an existing control file; never edit one by hand'), sequences prerequisites (lookup_docs first, ask user before scientific choices), and names an alternative (make_control_file) for the multiline case it refuses.

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