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

Beyond the annotations, the description adds important behavior: all booleans default true, jobs includes Speedbot Bootstrap broadcasts, webhook_secret is write-only, URL null removes push delivery, and the tool requires an agent key but never starts the runtime or authorizes work. These details enrich the annotation profile without contradiction.

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 dense but well-structured, opening with the core read/change behavior and then layering defaults, job-scope clarification, webhook setup, write-only secret semantics, and auth requirements. Every sentence contributes actionable information without verbosity.

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 7 optional parameters, no output schema, and non-readOnly behavior, this description covers all invocation-critical aspects: authentication, field semantics, defaults, webhook lifecycle, secret handling, and safety bounds. An agent can determine exactly what to send for a read or modify operation.

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 only 57%, and the description compensates by clarifying the jobs special case, default values for booleans, the webhook_url/webhook_secret relationship, and agent_key as auth. It leaves work and conversations somewhat generic as 'booleans', but this is adequate for a low-detail 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?

The description names a clear dual-mode operation: 'Read settings with no fields, or change enabled/work/jobs/conversations booleans.' It identifies the exact resource and fields, making it easy for an agent to distinguish this settings tool from siblings like speedbot_notifications.

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 gives explicit context for both read and modify usage: omit fields to read, set enabled:false to stop all notifications, mute a single category, or configure webhook delivery. It does not explicitly name sibling alternatives or exclusion cases, but the usage boundaries are clear enough for correct selection.

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