hook_function

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

With no annotations, the description handles behavioral disclosure well. It details that intercept mode injects custom JS with context variables, trace mode logs non-invasively, and mentions persistence and non-overridability. It could mention potential resource usage or removal mechanisms, but overall it is transparent.

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 a one-liner and bulleted arguments. While informative, it is somewhat verbose; for example, the context variable explanations could be condensed. Still, it remains clear and readable.

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 10 parameters, no output schema, and no annotations, the description is remarkably complete. It explains every parameter, the return value format, and gives usage patterns like examples for function_path. It covers both modes thoroughly.

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 description coverage is 0%, but the description provides extensive parameter semantics beyond the schema: explains function_path format, mode options, hook_code context variables, position values, and trace-related parameters. This adds significant meaning that the schema lacks.

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 starts with 'Hook or trace a function (v0.9.0 unified).' It clearly states the tool's purpose and distinguishes it as a unified replacement for older hook and trace functions. Sibling tools like hook_jsvmp_interpreter and trace_property_access are different, so this description effectively differentiates.

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 explains two modes ('intercept' and 'trace') with their requirements and behavior, e.g., 'Requires hook_code' for intercept. It provides context for when each mode is appropriate. However, it does not explicitly compare with siblings like hook_jsvmp_interpreter or trace_property_access, which would improve guidance.

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