create_hook

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true): it names both delivery sinks with concrete shapes, discloses that webhook targets are restricted to operator-allowed prefixes, warns that events are not replayed, explains the evaluation mechanism, and states nothing is ever traded. That is exactly the security/retention disclosure the annotations omit.

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-loads the core action in the first sentence, then layers delivery, lifecycle and safety caveats in short clauses. Dense but each sentence carries information; only the awkward multi-line `action` formatting slightly hurts scannability.

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?

For a create tool with a nested schema and no output schema, the description covers the lifecycle (evaluation by run_hooks/cron), delivery, and safety scope. Gaps remain around ticker/period meaning and what happens on name collision or re-creation, which matter for repeated calls.

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?

Top-level schema coverage is 0%, so the description must carry the load; it does well for `action` (with both target shapes and examples) and implies `condition` via the firing sentence, and nested $defs illustrate condition/series/indicator shapes. But `ticker`, `period`, `series` and `indicators` are never explained in the description, leaving half the required surface to inference.

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 and resource ('Save a condition hook') plus the trigger semantics ('when the condition fires on a new bar, a JSON event is delivered'). This clearly separates it from lifecycle siblings list_hooks, run_hooks and delete_hook, which create nothing.

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?

Tells the agent that the hook does nothing until run_hooks or the broker-analysis-hooks cron command evaluates it, and that past events are not replayed — essential context for deciding whether to create one. It does not explicitly say when to prefer this over, say, custom_analysis, but the operational context is strong.

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