evolve_mark_applied

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

The description adds significant behavioral context beyond annotations: it reveals that the tool sets a field (applied=1) that removes the suggestion from certain views, records a URL, enforces a non-empty pr_url gate, and notes that a human still reviews/merges. This workflow detail helps the agent understand consequences.

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 concisely written in four sentences, each adding distinct value: purpose, caller, effect, and a critical usage rule. It could be slightly tighter, but overall it is well-structured and front-loaded.

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 the tool's simplicity (2 required params, clear side effects), the description covers the main behavioral aspects and workflow steps. It does not discuss error cases or output schema (which exists), but the core information is sufficient for correct invocation.

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?

With 0% schema description coverage, the description partially compensates: it explains pr_url's role as a required gate and its non-empty constraint. However, it does not explain evolve_id, leaving its semantics implicit. This is adequate but not fully helpful.

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 clearly states the tool's purpose: to mark a format-evolution suggestion as 'APPLIED', with a specific caller context (evolve_applier child) and action (sets applied=1, records PR url). It distinguishes from sibling mark tools by specifying the exact resource type.

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 indicates when to use this tool ('after it has opened the PR') and provides a strong usage rule ('never mark a suggestion applied without a real pull request'). It does not explicitly contrast with sibling tools, but the context is clear enough for an AI agent to determine appropriate use.

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