forge

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

With no annotations provided, the description carries the full burden of behavioral disclosure and excels. It details the tool's read-only nature, event emission, no authentication/network/rate limits, error-handling approach (never throws, returns arrays), and optional parameter behavior. This covers safety, side effects, and operational constraints thoroughly beyond what a schema could convey.

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 well-structured with clear sections (Behavior, Use when, Do NOT use, Returns, Example) and front-loaded key information. While detailed, every sentence adds value (e.g., explaining validation checks, usage contexts, return structure). Minor verbosity in listing all checks keeps it from a perfect 5, but it remains efficient and organized.

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 complexity (validation with multiple checks) and lack of annotations/output schema, the description is highly complete. It explains the validation scope, behavioral traits, usage guidelines, parameter semantics, and return structure with examples. No critical gaps exist; an agent has all needed context to invoke and interpret results 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 schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the optional parameter's behavior: 'planPath is optional; when omitted, the most recently modified file in .forge/plans/ is used.' This clarifies the default logic, enhancing understanding beyond the schema's basic description.

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 with specific verbs ('structurally validate a forge plan JSON file') and resources ('plan JSON file'), distinguishing it from siblings like 'validate' (for single module build output) and 'iteration_state' (for attempt counts). It explicitly lists the validation checks performed, making the purpose highly specific and differentiated.

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 explicit 'Use when' scenarios (e.g., after planner writes a plan, debugging execution order issues, human pre-flight checks) and 'Do NOT use for' exclusions (e.g., executing a plan, validating single module output, inspecting retry history), with named alternatives like 'validate' and 'iteration_state'. This gives comprehensive guidance on when to use this tool versus others.

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