SiteSpeak Chatbot Manager

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

Annotations already establish that this is a non-read-only, non-destructive, open-world operation. The description adds useful context that indexing is kicked off as a side effect, but says nothing about indexing latency, async completion, permissions, or failure behavior.

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?

Two short sentences, no filler, with the action and its effect front-loaded before the input note. Every clause earns its place.

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 simple 3-parameter tool with full schema coverage and annotations covering the safety profile, the description covers the essentials. The only gap is what happens after indexing starts (status, return value), though no output schema exists to lean on.

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 the parameter docs already carry the load and the baseline is 3. The phrase 'a single page or site URL' adds a small amount of meaning about acceptable URL scope beyond the schema's terse 'The website URL to index.'

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 ('Add a website knowledge source by URL') and adds the operational effect ('start indexing it'), which separates it from read-oriented siblings like list_sources. It doesn't explicitly name recrawl_source, so the distinction from that nearest sibling is left implicit.

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?

'Add ... by URL' combined with the existing recrawl_source sibling implies this is for new sources rather than refreshing existing ones, but the description never says when to use this instead of recrawl_source. Usage is inferable rather than stated.

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

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

Annotations already declare this is a write operation (readOnlyHint=false), non-destructive, and closed-world, so the safety profile is covered without description help. The description adds the type-dependent field requirements, but says nothing about permissions, limits on number of messages, or what is returned on success.

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?

Two compact sentences, front-loaded with the purpose and then the conditional field rules. No wasted words, though the second sentence duplicates what the schema already states about type-dependent requirements.

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 no output schema, the description doesn't hint at what a successful add returns. It also covers only three of the nine enumerated types (ai, redirect, email) and leaves intercom, follow_up*, and escalate behavior unexplained, which is a meaningful gap for an agent choosing parameters.

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 description coverage is 100%, so every parameter is already documented in the schema (including the required-when-type conditions). The description largely restates those same type-to-field mappings and adds only the 'ai is default' detail, 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 gives a specific verb+resource (add a suggested message) and parenthetically defines what the resource is ('a clickable prompt shown to visitors'), which an agent can't get from the name alone. It doesn't explicitly name or contrast with the sibling tools (list_suggested_messages, update_suggested_message, remove_suggested_message), but the create semantics are unambiguous.

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?

It provides conditional guidance keyed on the 'type' value (ai vs redirect/email), which is genuinely useful for filling the form. However, it gives no when-to-use/when-not guidance relative to siblings and no prerequisites or conditions under which adding a suggested message is appropriate.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the return payload (settings, plan-allowed models, per-model credit cost), which matters since there is no output schema. It omits whether any auth/plan constraints affect what is returned.

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?

Two short sentences with no filler; the primary capability (current settings plus plan models and credit cost) is front-loaded and the workflow hint follows.

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 single-parameter read tool with full schema coverage and read-only annotations, the description supplies the essential return-content and sequencing context. It could be marginally more complete about what 'settings' includes, but nothing critical for correct invocation 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 description coverage is 100% and the sole chatbot_id parameter is already documented with its origin (from list_chatbots). The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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 (Get) and resource (a chatbot's current settings), and enumerates what the response contains: models allowed on the plan and credit cost per model. This clearly distinguishes it from the sibling list_chatbots and from update_chatbot_settings.

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?

"Read this before changing settings" gives an explicit sequencing rule that ties the tool to the update_chatbot_settings workflow, which is genuinely useful context. It stops short of naming alternatives or stating when-not to use it, so not a full 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the period scoping and the returned metric list, which is useful given there is no output schema, but it says nothing about auth needs, rate limits, or data freshness.

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?

A single front-loaded sentence with no filler. The enumerated metric list is a bit long but earns its place because no output schema exists to describe the return content.

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 read-only analytics tool, the description compensates for the missing output schema by naming the returned metrics, and annotations cover safety. The main gap is the absence of any routing versus the sibling get_chatbot_insights.

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 description coverage is 100%, so all four parameters including period, from, and to are already documented in the schema. The description only restates 'for a period' and adds no format or dependency detail beyond what the schema provides, so the baseline 3 applies.

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 (Get) and resource (chatbot analytics), and enumerates the metric groups returned, which lets an agent understand scope. However it does not differentiate itself from the similar-sounding sibling get_chatbot_insights.

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 phrase 'for a period' gives loose context, but there is no guidance on when to use this tool versus get_chatbot_insights or get_chatbot, and no stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the nature of the output (clustered themes, gap analysis), but says nothing about freshness, cost, or clustering behavior beyond the annotations.

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?

Two sentences, zero filler. The primary output (unanswered/answered themes) is front-loaded, and the usage hint follows.

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 no output schema, the description must convey return content, and it does specify the two theme categories. Coverage is nearly complete; only the default time window and any result limits are left unstated.

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 description coverage is 100%, including defaults for the from/to date window, so the schema carries parameter meaning. The description adds nothing about parameter semantics or the default 30-day reporting window, making 3 the correct baseline.

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 specific verb and resource ('Get AI-clustered question themes for a chatbot') and enumerates the two content categories returned (top unanswered, top answered). This lets an agent distinguish it from siblings like get_chatbot_analytics without opening either 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?

It gives a clear application context ('Use unanswered themes to suggest new content and messages'), which routes the agent toward the suggested-message tools. It stops short of stating when not to use it or contrasting it explicitly with get_chatbot_analytics.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds ordering behavior (oldest first), the default window (most recent messages), and how to page backwards, which is genuinely useful context beyond the annotations. It stops short of describing the return shape or page size limits.

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?

Two short sentences, front-loaded with what is returned and in what order, followed by the paging instruction. No filler and nothing an agent must wade through.

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 read-only paginated list tool whose safety profile is carried by annotations and which has no output schema, the description covers ordering, default window, and paging adequately. The dangling reference to 'has_older' - a field the agent cannot resolve from the schema or a declared output - is the one real gap.

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 description coverage is 100%, so limit/offset/chatbot_id/visitor_id are already documented, and the description largely restates the offset/default-window behavior. It does add the relationship between offset and the undecorated 'has_older' value, but since has_older appears in neither the schema nor an output schema, that reference is ambiguous rather than clarifying.

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 with scope: 'Get the messages in one inbox thread (visitor), oldest first.' It also names the ordering, which helps distinguish it from list_inbox_threads. It does not explicitly name a sibling alternative, so it falls short of 5.

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 paging guidance ('use offset with has_older to page back through long threads') but never states when to reach for this tool versus list_inbox_threads or reply_to_thread, nor any prerequisite such as needing a visitor_id sourced elsewhere. Usage is implied by the scoping to a single thread rather than explicitly framed.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds scope (account/team chatbots) and, usefully given there is no output schema, the return shape (id, name, type). It does not mention pagination or whether the full set is returned.

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?

Two short sentences, front-loaded with the action and scope, followed by return fields and a routing hint. The parenthetical restating team scope is mildly redundant but not wasteful.

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 zero-param read-only list tool whose annotations carry the safety profile, the description covers purpose, scope, and return fields adequately. Only minor gaps remain: no output schema or mention of pagination/ordering.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. No parameter-level meaning is needed.

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 (List) and resource (chatbots) and scopes it to "your account can manage (your current team's chatbots)." The list-vs-get distinction against the sibling get_chatbot is implied by the name, but the text does not explicitly name or contrast that sibling.

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?

Usage is only implied: "Use the id with the other tools" tells the agent why the returned ids matter but not when to call this versus get_chatbot or the list_* siblings. There are no explicit when/when-not conditions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar for the description is lower. The description adds little beyond them apart from noting the chatbot scoping; it does not describe result shape, ordering, or what pagination implies across pages.

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?

A single front-loaded sentence naming the operation first and the filters second, with no redundant or filler text. Every clause earns its place.

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 read-only, fully schema-documented list tool with no output schema, the description is nearly sufficient: purpose, scoping, and filter dimensions are all covered. The remaining gap is that it says nothing about the returned thread payload or pagination semantics, which an agent must infer from the schema.

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 description coverage is 100%, so every parameter (page, search, status, feedback, chatbot_id) is already documented in the schema, including the default status of 'open'. The description's restatement of the filters adds no syntax or format detail beyond what the schema provides, making the baseline 3 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?

States a specific verb and resource ('List inbox conversation threads for a chatbot') and enumerates the filter dimensions, so the agent knows exactly what the tool returns. It does not distinguish itself from siblings like get_thread_messages (which returns message bodies) or update_thread_status, leaving the boundary to inference.

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 usage through its filter list (status, feedback, text search), which suggests when a caller would reach for it. However it never states when to use this versus get_thread_messages for reading a thread, nor any prerequisites or exclusions, so guidance remains implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are returned newest-first and paginated at 50 per page, which tells the agent how to iterate.

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?

A single, tight sentence with the resource definition and the two key behavioral facts (ordering, page size) front-loaded. Every clause earns its place; nothing is padded.

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 read-only, two-parameter listing tool with full schema coverage and annotations carrying the safety profile, the description is nearly complete. It could say a bit more about how to detect the end of pagination or whether an empty result is normal, but nothing critical 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 description coverage is 100%, so both parameters are already documented in the schema. The description's 'paginated 50 per page' merely restates the schema's page description rather than adding format, bounds, or ordering semantics beyond it.

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 ('List') and resource ('leads') and goes further by defining what a lead is ('visitors who submitted an email or phone via the lead-capture form'), which disambiguates the resource in a way the name alone cannot. No sibling tool overlaps this resource, so confusion risk is minimal.

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 makes the tool's domain clear (chatbot-scoped lead retrieval) so usage is implied, but it never states when to reach for this tool, what prerequisites exist beyond chatbot_id, or what to do when no leads exist. No alternative tool is named or excluded.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the pagination cadence (50 per page), but that fact is also present in the page parameter schema, so it contributes little new behavioral context and says nothing about auth, ordering, or empty states.

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?

Two short sentences with no filler; the core purpose is front-loaded before the pagination note. Every clause carries information.

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 simple two-parameter read-only list tool with no output schema, the description is nearly sufficient, and the mention of 'training status' hints at the returned content. It could still note ordering or what an empty result means, but nothing essential to correct invocation 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 description coverage is 100%, so both chatbot_id and page are already documented in the schema. The description restates the 50-per-page detail but adds no syntax, format, or default-value meaning beyond what the schema provides.

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 ('List a chatbot's knowledge sources') plus the scope of what is returned ('their training status'). This clearly separates it from mutating siblings like add_source and recrawl_source, though it never names them explicitly.

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?

There is no guidance on when to use this tool versus alternatives such as get_chatbot or recrawl_source, nor any stated prerequisites. The agent must infer usage purely from the name and verb.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the downstream id-usage behavior but says nothing about ordering, pagination, or what happens for a chatbot with no suggested messages.

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?

Two short sentences, front-loaded with the action and scope, with the second sentence adding a concrete follow-up step. No filler.

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 single-required-param read tool with full schema coverage and no output schema, the description covers what it is and what the result is used for. It could say more about the shape or ordering of the returned list, but nothing essential to calling it 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?

There is a single parameter (chatbot_id) with 100% schema description coverage, so the schema already carries the semantics. The description's 'a chatbot's suggested messages' confirms scope but adds no format or constraint detail beyond 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?

The description names a specific verb ('List') and resource ('suggested messages') and adds a clarifying gloss — 'the clickable prompts shown to visitors' — that separates this from thread messages or other chatbot content. It does not explicitly contrast with sibling list tools, but the object being listed is unambiguous.

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?

It gives clear workflow context: 'Use the returned id with update_suggested_message or remove_suggested_message,' which tells the agent this is a read-first step in a manage-messages flow. There are no explicit exclusions or alternate retrieval paths, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the agent knows this is a non-destructive write against external content. The description reinforces that it operates on an existing source rather than creating one, but adds nothing about whether the recrawl is async, how long it takes, or whether it can be triggered repeatedly.

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?

A single front-loaded sentence with zero filler; the verb and resource lead and the outcome clause follows.

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 two-parameter mutation with full schema coverage and annotations carrying the safety profile, the definition is nearly complete. The only material gap is what the caller should expect after invoking it (synchronous re-index vs. queued job), and no output schema exists to answer that.

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 description coverage is 100% and both parameters are documented in the schema, including the useful hint that source_id comes from list_sources. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 (re-index) and resource (existing knowledge source), and the word 'existing' implicitly distinguishes it from add_source and list_sources. It does not explicitly name a sibling, so it stops short of a 5.

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 purpose clause 'to pick up its latest content' implies the when-to-use condition (source content has changed), but there is no explicit guidance, no prerequisites, and no named alternative. Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this permanently deletes data. The description adds only the scoping phrase "from a chatbot" and the id-sourcing hint, with no mention of irreversibility, confirmation, or permission requirements, but with annotations carrying the safety profile a 3 is appropriate.

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?

Two short sentences with no filler, and the core action is front-loaded before the prerequisite hint. Every clause earns its place.

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 two-parameter destructive delete with full schema coverage and annotations supplying the safety profile, the description supplies everything needed to invoke it correctly. It could go further on irreversibility or confirmation behavior, but nothing essential 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 description coverage is 100%, so both chatbot_id and suggested_message_id are already documented, including the note that the id comes from list_suggested_messages. The description restates the same provenance without adding format, validation, or edge-case detail, so baseline 3 applies.

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 ("Remove a suggested message from a chatbot"), which an agent can distinguish from update_suggested_message and add_suggested_message. It also names the sibling list_suggested_messages as the id source, though it does not explicitly contrast itself against those siblings.

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?

It gives clear actionable context: obtain the id from list_suggested_messages first, which is a real prerequisite step for calling this tool. It stops short of stating when not to use it or how it relates to update_suggested_message, so it is not a full when/when-not statement.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true. The description usefully adds non-obvious behavior: the visitor sees the message in the chat widget (or WhatsApp/Google Chat) and a 30-minute live chat session starts. It does not, however, explain the destructive aspect or whether the send is irreversible.

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?

Two sentences, zero filler, and the core action plus its visible consequence are front-loaded before the approval caveat. Every clause earns its place.

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 a full-schema parameter set, no output schema, and annotations covering the safety profile, the description is nearly sufficient. A note on irreversibility or delivery failure handling would fully close the gap for this side-effecting send 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 description coverage is 100%, so the baseline is 3. The description adds only the disposition of 'message' (the visitor-facing reply text); the helpful note that visitor_id comes from list_inbox_threads lives in the schema, not the description, so no extra value is contributed here.

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 precise verb+resource+actor: 'Send a human agent reply to the visitor in an inbox thread.' It clearly differentiates from siblings like add_suggested_message or update_thread_status by naming the actual sending action and its recipient.

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 closing line 'Only send text the user has approved' gives a real usage constraint, but the description never routes the agent among alternatives (e.g., when to reply directly vs. queue a suggested message, or how this relates to update_thread_status). Usage is implied rather than compared against siblings.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, so the write/mutating nature is already covered. The description adds genuinely new behavioral context beyond that: 'Only the fields you pass are changed' discloses patch semantics, which materially changes how an agent should build the request. It does not cover auth or reversibility, but the partial-update disclosure is the key missing piece from the annotations.

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 short sentences, front-loaded with the core action, then the partial-update semantics, then the cross-call prerequisite. No filler. Slightly fragmented into three sentence threads rather than one flowing unit, but every sentence earns its place.

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 15-parameter mutation tool with no output schema, the description covers the two things an agent cannot deduce from structure alone: that it is a partial update and that gpt_model requires a prior lookup. Remaining gaps are minor since the schema already documents per-field constraints and dependencies.

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 description coverage is 100% and every parameter (ranges, max lengths, formats) is already documented inline. The description's note that gpt_model must be in allowed_models repeats the schema's own constraint, so it adds no meaning beyond the structure. Baseline 3 applies.

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 ('Update a chatbot's settings'), which an agent can map to a single chatbot entity. Sibling tools are all distinct resources (sources, threads, leads, suggested messages), so no explicit differentiation is needed, but the description does not call that out.

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 a concrete workflow prerequisite: 'Call get_chatbot first to see allowed_models before changing gpt_model.' It implies when the tool is used (changing existing settings) but offers no explicit when-not-to-use or alternative routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=false. The description adds the partial-update rule ('Only the fields you pass are changed'), which is useful but largely inferable from the schema marking only the two ids as required. It never explains what the destructiveHint actually implies (overwritten values, irreversibility), so behavioral coverage remains thin despite the annotation relief.

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 short sentences, each carrying a distinct fact (purpose, update semantics, id source), with the core action front-loaded. Nothing is padded or redundant.

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 no output schema, the definition still covers purpose, mutation semantics, and id acquisition, and annotations cover the safety profile. It is slightly short on what a successful update returns or what happens with an unknown id, but nothing essential for invoking the tool 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 description coverage is 100%, so every parameter (name, type, action, prompt, ids) is already documented with constraints like max length and the type enumeration. The description adds only the id-provenance hint, which the schema also states, so it does not exceed the baseline.

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 ('Update') and resource ('an existing suggested message'), which clearly separates it from add_suggested_message and remove_suggested_message in the sibling list. It does not explicitly name those siblings, but the resource anchoring makes disambiguation easy.

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 a concrete prerequisite workflow: 'Get the id from list_suggested_messages,' naming the sibling that supplies the required suggested_message_id. There are no when-not-to-use conditions, so it stops short of the top tier.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so an agent knows this is a scoped, non-destructive write. The description adds little beyond that: it does not say whether the change is reversible, what happens to prior status, or whether snooze/priority require extra fields. With annotations covering the safety profile, this is adequate but thin.

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?

Two short sentences with no filler, and the core action is front-loaded before the value clarification. Every clause earns its place.

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 3-parameter, fully schema-documented mutation with annotations carrying the safety profile and no output schema, the description covers what the tool does and the key status values. Minor gaps around reversibility and interaction with sibling write tools keep it from a 5.

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 description coverage is 100%, so all three parameters are already documented in the schema, including the enum-like status values and their meanings. The description restates the allowed values rather than adding new semantics, so the baseline of 3 applies.

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 ('Set an inbox thread status') and enumerates the accepted status values, which clearly separates it from sibling reads like get_thread_messages and list_inbox_threads. It does not explicitly name a competing write sibling such as reply_to_thread, so it falls short of full sibling differentiation.

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 note that '"archived" to mark a thread as done' gives semantic guidance on one value, and the allowed list bounds the input. However, there is no when-to-use vs when-not guidance and no mention of the interaction with reply_to_thread or other mutation siblings, leaving usage largely implied.

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