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

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds critical context they cannot: the signing secret is returned ONCE, the exact signature header format and HMAC construction, the default scoping of account_ids, and the https-only constraint. This is exactly the value-add the description should provide.

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?

Dense but front-loaded: purpose first, then the secret/signature contract, then event vocabulary, then usage conditions and the exclusion. Every clause carries information. It is one long paragraph, so a reader must parse carefully, but there is no filler or repetition.

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?

With an output schema present the description needn't enumerate return fields, yet it still flags the one-time secret exposure that matters most for correct client handling. Combined with the event list, scoping default, and routing guidance, an agent has everything needed to select and invoke the tool correctly against its siblings.

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%, so baseline would be 3, but the description adds real meaning the schema lacks: it enumerates the concrete event names (message.received, connection.new, account.status_changed, quota.threshold_reached, quota.reached, '*'), which the schema leaves as an opaque string array with no enum, and it clarifies the account_ids default (omit = all accounts). It does not restate the url or idempotency_key semantics, which the schema already covers well.

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 first sentence states a specific verb+resource ("Register a URL to be called when something happens on LinkedIn") and immediately frames the outcome (react instead of polling). It is clearly distinct from the sibling delete/update/list/test_webhook_endpoint tools, which share the resource but differ in verb.

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?

Explicit when-to-use ("Use when the user wants to react to a reply, a new connection, a quota alert or a job event from n8n, Make or their own code"), a prerequisite ("needs an https URL they control"), and an exclusion ("Not for the model to call itself"). Nothing is left to inference.

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