subscribe

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

With no annotations provided, the description carries the full burden and does well: it discloses that subscriptions persist in ~/.nexus-webhooks.json and survive server restarts, which is a meaningful side-effect trait. It does not mention duplicate-subscription behavior or whether registration overwrites existing entries, but the persistence disclosure goes beyond a minimal description.

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?

Three sentences with zero waste: purpose is front-loaded, the return value is stated, and persistence behavior follows. Every sentence earns its place and the description is appropriately sized for a 2-parameter tool.

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 tool with 2 parameters, no annotations, and no output schema, the description covers the essentials: what it does, what it returns (subscription id UUID), and how subscriptions behave across restarts. Minor gaps remain such as duplicate-subscription semantics and the exact JSON envelope of the response, but nothing an agent needs to call it correctly is missing.

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 coverage is 100%, with both event_type (including enum meanings) and webhook_url (including payload format) fully documented in the schema. The description adds only marginal value here, mentioning the returned subscription id but no additional param semantics, so the baseline of 3 is appropriate.

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 states a specific verb and resource: 'Register a webhook URL to receive HTTP POST notifications when a memory event of the given type fires.' It clearly differentiates from sibling tools like unsubscribe and list_subscriptions by focusing on the registration action and the returned subscription id.

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 implies when to use it (when HTTP POST notifications about memory events are desired) and links the returned id to the unsubscribe sibling, but it never explicitly names alternatives or states when not to use this tool. The lifecycle hint is useful but leaves routing decisions to inference.

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