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

Goes well beyond the annotations: a test message is sent first unless send_test is false, nothing is saved or charged if the test fails, tokens are stored encrypted and never shown back, and each call costs $0.001 (free on failure). It also discloses that a webhook request is signed with a secret returned only once and that account.credential_added signals persistence — exactly the mutation side-effects an agent needs before committing.

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?

Purpose is front-loaded, but the body is one dense run-on with stacked parentheticals ('(ntfy's token too, with ask_owner_for) (from_a_terminal does the same from a terminal)') that force re-reading. Nearly all content earns its place, but the structure makes it harder to parse than it needs to be.

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 13-parameter mutation with no output schema, the description covers cost, test-send semantics, failure behavior, credential handling, and the owner-link flow. It leaves open whether channel names must be unique and what an error response looks like, but nothing critical to calling 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?

With schema description coverage at 15% across 13 parameters, the description carries the burden and mostly succeeds: it maps credentials to kinds (bot_token + chat_id for Telegram, topic/server/access_token for ntfy, user_key/app_token for Pushover, url for webhooks) and covers send_test and ask_owner_for. It is slightly inconsistent in naming the generic webhook field 'url' while the schema also exposes a separate 'webhook_url', and it references a from_a_terminal option absent from the schema.

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 concrete verb and resource ('Save a place to send messages, by name') and immediately enumerates the supported channel kinds with the credential each requires. An agent can tell this apart from notify_send or notify_list_channels without opening any schema.

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 the delegated-authorization invocation path (call without the secret and get an owner link) and mentions from_a_terminal as an equivalent route, which is useful context. However, it never says when to use this versus notify_send, notify_request_approval, or notify_list_channels, so the sibling routing 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.