prescribe_frankability_fixes

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

With no annotations, the description carries the full burden. It discloses that the tool generates prescriptions and that the agent must apply them via a separate tool, implying no mutation happens here. It also describes the return shape (JSON with schema version, opId, prescriptions). However, it does not explicitly state side effects, permissions, or error behavior of this specific tool, and spends significant space describing the sibling apply tool's behavior.

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 front-loaded with purpose and uses clear headings/bullets, but it is fairly long. It includes a full list of op kinds and detailed behavior of the follow-up apply tool; these are useful in context but could be trimmed if those details live in sibling tool descriptions.

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 one parameter, an output schema, and a complex workflow, the description is highly self-contained. It explains what the prescription contains, how to handle findings with and without proposedOps, what the follow-up tool does, and when to stop—covering all the information an agent needs to invoke and use this 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?

The input schema has one required string param with 0% schema description coverage. The description fully compensates by saying 'symbols_dir: Absolute path to the symbols/ directory', which gives the agent precise, actionable semantics beyond the bare schema.

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 specific verb ('Generate') and a clear resource ('LLM-ready prescriptions for frank-audit findings that can't be auto-fixed'), immediately distinguishing this tool from adjacent siblings like apply_frankability_edit_ops. It also enumerates the prescription contents, which further clarifies the tool's role as a planning/proposal generator.

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 an explicit 4-step workflow: call this tool, inspect/modify proposedOps, call apply_frankability_edit_ops, and repeat. It clearly states the intended use case (findings that can't be auto-fixed) and gives specific instructions for the no-proposedOps case, including a list of valid op kinds.

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