dosai_update_bot_settingsChange one or more bot settings. Only the fields you pass change. This affects how the bot talks to real clients immediately, so confirm the change with the user first. Requires admin or owner role.
| Name | Required | Description | Default |
|---|---|---|---|
| settings | Yes | ||
| project_id | Yes | Project id, as returned by dosai_list_projects. |
Changes observed during successful MCP inspections.
Input schema / properties / settings / properties / buffer_delay_media_secondsAdded value: +{
+ "description": "Same as buffer_delay_seconds when the client started with a photo, voice message or video (they take longer to send). Range 0-120.",
+ "maximum": 120,
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / settings / properties / buffer_delay_seconds / descriptionPrevious value: -"Seconds the bot waits for the client to finish typing before it answers. Range 0-120."New value: +"Once the client sent a second message, seconds of silence the bot waits for before it answers all of them at once. Every new message restarts the count. Default 7. Range 0-120."Input schema / properties / settings / properties / buffer_first_message_secondsAdded value: +{
+ "description": "Seconds the bot waits after a single client message in case another one follows, before it starts the reply. Lower = answers faster; higher = less often answers half a thought. If the client writes again while the bot is already writing, the draft is discarded and half of its price is charged. Default 6. Range 0-60.",
+ "maximum": 60,
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / settings / properties / handoff_reply_textAdded value: +{
+ "description": "Your own line for the moment the bot handed the case to a human and had nothing of its own left to say (a notify function fired, the model returned no text). Empty = our line \"Спасибо! Передаю вашу заявку специалисту…\". To say NOTHING at all, use the per-function switch instead (dosai_update_function, silent_after_call).",
+ "maxLength": 500,
+ "type": "string"
+}Input schema / properties / settings / properties / engage_mode / descriptionPrevious value: -"Who the bot answers on WhatsApp (and on Instagram unless instagram_engage_mode is set): all = only people who write for the first time after the channel was connected, existing_too = everyone who writes, old contacts too, ad_gated = only people who came from ads."New value: +"Who the bot answers on WhatsApp (and on Instagram unless instagram_engage_mode is set): all = only people who write for the first time after the channel was connected, existing_too = everyone who writes, old contacts too, except chats where the owner or an operator wrote in the last 7 days, ad_gated = only people who came from ads."Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only flag it as a non-readonly, non-destructive, non-idempotent mutation. The description adds what annotations cannot: that it is a partial patch ('Only the fields you pass change'), that changes hit live client conversations immediately, and that an elevated role is needed. It does not describe the response, but with annotations covering the safety profile this is above the bar.
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?
Four short sentences, each load-bearing: what changes, the partial-update rule, the live-impact warning, and the auth requirement. The mutation semantics come first and the risk/auth constraints follow, which is the right order.
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 27-field nested settings mutation with no output schema, the description covers the things an agent could get wrong: assuming full replacement, skipping user confirmation, missing the role requirement. The schema handles per-field meaning and even cross-references dosai_get_bot_settings, so only the return value goes unmentioned.
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?
Both top-level parameters are documented in the schema, and the nested settings object is unusually well annotated, but the description still contributes the one fact the schema does not state as a calling rule: unpassed fields are left untouched. That directly shapes how the agent should construct the 'settings' object.
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 ('Change one or more bot settings') and immediately clarifies the partial-update semantics. It does not name a sibling such as dosai_get_bot_settings for reading the current values, so it stops short of the top score, but an agent can tell what it does without opening the 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?
Gives real preconditions: confirm with the user first, and admin/owner role required. It does not explicitly route the agent to dosai_get_bot_settings for reading current values or name any alternative, so it is clear context rather than full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.