Manage and optimize SiteSpeakAI chatbots from an AI agent in plain English: read analytics, tune prompts and model, manage knowledge sources and suggested messages, enable lead capture and human handoff, and triage the inbox.
Scored across 16 tools
Each tool targets a distinct resource and action—sources, suggested messages, chatbots, analytics, insights, threads, leads—with no overlapping purposes. Even similar tools like get_chatbot_analytics and get_chatbot_insights are clearly separated by quantitative metrics versus AI-clustered themes. Tools are unambiguous and an agent can easily select the correct one.
All tool names follow a consistent verb_noun pattern (add_, get_, list_, recrawl_, remove_, update_) in snake_case. The verbs are uniformly descriptive (add, get, list, recrawl, remove, update) and the nouns are specific resources. No deviations or mixed conventions are present.
With 16 tools, the count is just over the ideal 3-15 range but still appropriate for a chatbot management domain that covers sources, messages, threads, leads, analytics, and settings. The tools are well-scoped and not excessive; each one serves a clear purpose. It feels slightly heavy but not problematic.
The tool surface covers the core chatbot management operations: reading and updating settings, managing knowledge sources (add, list, recrawl), full CRUD for suggested messages, and viewing/updating inbox threads. Minor gaps exist, such as no delete for sources or chatbots, and no export for leads, but agents can work around these using the available tools. The domain is well-covered overall.
Add a website knowledge source by URL and start indexing it. Provide a single page or site URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The website URL to index. | |
| title | No | Optional label; defaults to the URL. | |
| chatbot_id | Yes | The chatbot id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It mentions 'start indexing it' but does not disclose side effects, prerequisites (e.g., valid chatbot_id), whether URLs already indexed are handled, asynchronous behavior, or permissions required.
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 brief and front-loaded with the core action. The second sentence ('Provide a single page or site URL') is slightly redundant but not harmful. Overall it is concise with no wasted words.
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?
Given no output schema, the description does not explain what the tool returns after adding a source (e.g., a source ID or confirmation). It also does not mention whether the indexing is immediate or asynchronous, or any success/failure signals. Missing important contextual information for an agent.
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?
Parameter descriptions in the schema cover 100% of parameters. The description adds only a minor clarification that the URL can be a single page or site, and that the title is optional. This provides marginal added value beyond the schema, earning the baseline score.
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 clearly states the tool adds a website knowledge source by URL and indexes it. The verb 'add' and resource 'knowledge source' are specific and distinct from sibling tools (e.g., list_sources, recrawl_source).
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 indicates to provide a single page or site URL, but lacks explicit guidance on when to use this tool versus alternatives like list_sources (to check existing sources) or recrawl_source (to reindex). No exclusion criteria or context for use given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a suggested message (a clickable prompt shown to visitors). For type "ai" (default) provide a prompt - the message sent when clicked. For redirect/email types provide an action (a URL or email address).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The button label shown to visitors (max 100), e.g. "Pricing Plans". | |
| type | No | ai (default), redirect, email, intercom, follow_up, follow_up_link, follow_up_email, escalate. | |
| action | No | A URL or email (max 200). Required for type redirect, email, follow_up_link, follow_up_email. | |
| prompt | No | The message sent when clicked (max 200). Required for type ai and follow_up. | |
| chatbot_id | Yes | The chatbot id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Explains behavior per type (sending message vs redirect) but does not disclose permissions, idempotency, or 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?
Extremely concise: two sentences, front-loaded with purpose. Every sentence adds value.
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?
Adequate for a creation tool with 5 parameters and no output schema. Missing details on return value or duplicate handling, but sufficient for typical use.
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?
100% schema description coverage gives baseline 3. Description adds meaning by linking prompt and action to the type (e.g., 'prompt required for ai and follow_up'), which is not fully explicit in 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?
Clear verb+resource: 'Add a suggested message (a clickable prompt shown to visitors).' Distinguishes from sibling tools like list_suggested_messages and update_suggested_message.
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 guidance per type: 'For type 'ai' (default) provide a prompt... For redirect/email types provide an action...' Clear context but no explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a chatbot's current settings plus the models allowed on its plan and the credit cost per model. Read this before changing settings.
| Name | Required | Description | Default |
|---|---|---|---|
| chatbot_id | Yes | The chatbot id (from list_chatbots). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it is a read operation ('Get' and 'Read this before changing'), but does not detail authorization, rate limits, or other behavioral aspects.
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, front-loaded with the core purpose, no unnecessary words. Every sentence serves a purpose.
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?
Given no output schema, the description adequately lists what the tool returns (settings, plans, credit costs). Single parameter fully covered by schema, and usage hint provided. Complete for its complexity.
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% with one parameter (chatbot_id). The description adds context: 'from list_chatbots', which provides additional meaning beyond the schema, improving usability.
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 specifies the verb 'Get' and the resource 'chatbot's current settings plus models and credit cost', clearly distinguishing from sibling tools like get_chatbot_analytics or 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?
Explicitly advises 'Read this before changing settings', indicating when to use the tool and implying a sequence of operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a chatbot's analytics for a period: conversation volume, feedback, answered-question %, negative-sentiment %, popular sources/categories, top countries.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ISO date; used when period=custom. | |
| from | No | ISO date; used when period=custom. | |
| period | No | last_7_days, last_30_days (default), or custom. | |
| chatbot_id | Yes | The chatbot id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits such as data freshness, rate limits, authentication requirements, or whether the operation is read-only. The description implies a query but lacks explicit behavioral context.
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 a single sentence that efficiently lists the key metrics. It is concise but lacks structural elements like bullet points or separate sections. Still, it is appropriately sized for the tool's simplicity.
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?
The tool has no output schema and minimal annotations. The description explains what metrics are returned, which is useful. However, it does not mention data aggregation details, time range behavior, or limitations. Given the tool's simplicity, the description is moderately complete but could be improved.
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 value by enumerating the metrics returned (e.g., conversation volume, feedback), but does not further explain parameter specifics 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?
The description clearly states the tool retrieves analytics for a chatbot and lists specific metrics (conversation volume, feedback, percentages, sources, countries). This distinguishes it from sibling tools like get_chatbot_insights, which likely provides different analytics.
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 does not provide any guidance on when to use this tool versus alternatives (e.g., get_chatbot_insights). No when-to-use or when-not-to-use context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI-clustered question themes for a chatbot: top unanswered questions (knowledge/source gaps) and top answered questions. Use unanswered themes to suggest new content and messages.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ISO date (default today). | |
| from | No | ISO date (default 30 days ago). | |
| chatbot_id | Yes | The chatbot id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. The name 'get' and description imply a read operation with no side effects. However, it lacks disclosure about authentication, rate limits, or any potential overhead. The description is adequate but not detailed beyond the obvious.
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 two sentences: the first defines the output, the second suggests a use case. It is front-loaded and efficient, with no unnecessary words. Every sentence adds value.
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?
The tool has no output schema, so the description should provide information about the return structure. It only mentions 'question themes' but does not specify whether it's a list, object, or what fields are included (e.g., question text, count, themes). Given the complexity and lack of output schema, the description is incomplete for a developer to use confidently.
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% with descriptions for each parameter (chatbot_id, from, to). The description adds context about what the data represents (themes), but it does not enhance understanding of the parameters themselves. The parameter meanings are fully covered by the schema, so baseline 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 clearly states the tool retrieves 'AI-clustered question themes' and specifies the two categories: top unanswered and top answered questions. The verb 'Get' and resource 'chatbot insights' make the purpose obvious. It distinguishes itself from sibling tools like get_chatbot_analytics and list_sources by focusing on question themes.
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 provides a use case: 'Use unanswered themes to suggest new content and messages.' This implies when to use the tool (e.g., for content improvement). However, it does not explicitly mention when not to use it or compare to alternatives like get_chatbot_analytics, so context is clear but exclusions are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the messages in one inbox thread (visitor), oldest first. Returns the most recent messages by default; use offset with has_older to page back through long threads.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max messages per page (default 100, max 200). | |
| offset | No | Skip this many of the most recent messages to page further back (default 0). | |
| chatbot_id | Yes | The chatbot id. | |
| visitor_id | Yes | The thread/visitor id (from list_inbox_threads). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses ordering and pagination behavior but mentions 'has_older' which is not in schema and does not describe error handling, rate limits, or auth requirements.
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 with zero waste. Front-loads the purpose and then provides pagination guidance efficiently.
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?
Adequately covers core functionality and pagination for a read tool. Could mention response format or limitations of offset/limit, but overall complete given no output 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 coverage is 100%, baseline 3. Description adds meaning beyond schema: explains offset skips most recent messages, limit is max per page, and visitor_id comes from list_inbox_threads.
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?
Describes the tool with specific verb 'Get', resource 'messages in one inbox thread (visitor)', and ordering 'oldest first'. Distinguishes from sibling tools like list_inbox_threads which list threads, not messages.
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?
Provides clear guidance on default behavior (returns most recent messages) and how to paginate (use offset with has_older). However, does not explicitly compare with alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the chatbots your account can manage (your current team's chatbots). Returns each chatbot id, name and type. Use the id with the other tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It states the scope and return fields but does not disclose any behavioral aspects like read-only nature, pagination, rate limits, or authorization requirements. This is adequate but incomplete.
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 are concise and front-loaded with the purpose. Every sentence adds value, no fluff.
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 list tool with no output schema, the description explains the return values. It lacks details on sorting or data structure, but given the low complexity, it is mostly complete.
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 are zero parameters, so baseline is 4. The description adds value by specifying what is returned (id, name, type), which is not in 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 clearly states the tool lists chatbots the user's account can manage, specifying the scope ('current team's chatbots') and the returned fields (id, name, type). It distinguishes from sibling tools like get_chatbot (single) and list_sources.
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 explicitly says 'Use the id with the other tools,' providing clear guidance on how to use the output. However, it doesn't compare to alternatives like get_chatbot or list_sources, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List inbox conversation threads for a chatbot. Filter by status (open/closed/all) and feedback (positive/negative), and search message text.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (15 per page). | |
| search | No | Search message text. | |
| status | No | open (default), closed, or all. | |
| feedback | No | Filter threads by message feedback: positive or negative. | |
| chatbot_id | Yes | The chatbot id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With empty annotations, the description carries the full burden. It discloses filtering and search behavior but does not mention pagination details, default sort order, authorization requirements, or any side effects. It is partially transparent but lacking key behavioral traits.
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 a single sentence, which is concise and front-loaded with the primary purpose. It includes the main filtering options without extraneous detail. Could be slightly improved by structuring into a list or adding a sentence about output, but overall efficient.
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?
The tool has 5 parameters and no output schema. The description focuses entirely on input filters, omitting critical information about what the response contains (e.g., thread fields, pagination metadata). For a list tool without output schema, this is a significant 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 the schema already documents each parameter. The description echoes the filters but does not add new semantics beyond what the schema provides, such as default values (e.g., status default 'open') or usage constraints.
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 clearly states the action (list), the resource (inbox conversation threads for a chatbot), and the key filtering options (status, feedback, search). This distinguishes it from siblings like get_thread_messages which retrieves specific thread messages or update_thread_status which modifies status.
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 when to use (to list threads) but does not explicitly state when to avoid it or provide alternatives. No exclusionary criteria or comparative guidance against siblings, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a chatbot's captured leads (visitors who submitted an email or phone via the lead-capture form). Newest first, paginated 50 per page.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (50 per page). | |
| chatbot_id | Yes | The chatbot id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the type of data (leads), ordering (newest first), and pagination (50 per page). This is sufficient for a list tool, though it could mention authentication or scope.
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 a single, well-structured sentence that front-loads the core purpose and includes key behavioral details. No wasted words.
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 list tool without an output schema, the description adequately covers what the tool does, what it returns, and how results are ordered/paginated. Given sibling tools and low complexity, it is complete.
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% with descriptions for both parameters. The description adds context about pagination and ordering but does not provide additional semantics beyond what the schema already conveys. Baseline score 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 clearly states the tool lists captured leads (visitors who submitted email or phone via lead-capture form), specifies ordering (newest first), and pagination (50 per page). This is a specific verb+resource that distinguishes it from sibling tools like list_inbox_threads or list_chatbots.
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 when a chatbot's leads are needed, and the context of sibling tools (e.g., list_inbox_threads, list_chatbots) provides differentiation. However, it does not explicitly state when to use this tool vs alternatives or include exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a chatbot's knowledge sources and their training status. Paginated at 50 per page.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (50 per page). | |
| chatbot_id | Yes | The chatbot id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It mentions pagination and the return content (knowledge sources and training status) but does not explicitly state that the tool is read-only or disclose any side effects. However, the purpose is clear enough for a list operation.
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 a single, clear sentence that immediately conveys the tool's purpose and key feature (paginated at 50 per page). No unnecessary words.
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 list tool with two parameters and no output schema, the description is sufficient. It covers what the tool returns and pagination. It could mention sorting or filtering, but that is not essential.
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%, but the description adds value by stating the page size (50 per page) and linking chatbot_id to the chatbot's knowledge sources, which is not fully captured in the schema descriptions.
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 clearly states the verb 'List' and the resource 'a chatbot's knowledge sources and their training status'. It also includes pagination detail, which differentiates it from sibling tools like add_source or recrawl_source.
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 the tool is for listing sources but does not explicitly state when to use it over siblings like add_source or recrawl_source. No context about prerequisites or alternatives is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a chatbot's suggested messages (the clickable prompts shown to visitors). Use the returned id with update_suggested_message or remove_suggested_message.
| Name | Required | Description | Default |
|---|---|---|---|
| chatbot_id | Yes | The chatbot id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are empty, so the description carries full burden. It does not disclose behavioral traits like read-only nature, rate limits, or side effects. The description is minimal and adds no transparency beyond the name.
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 a single, well-structured sentence that front-loads the purpose and adds downstream utility. No wasted words.
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 tool with one parameter and no output schema or nesting, the description covers core functionality and use of results. Could mention that it returns a list of suggested messages, but the name implies 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?
The schema coverage is 100% with a clear description for chatbot_id. The tool description adds no additional meaning beyond the schema, so baseline score 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 clearly states the tool lists a chatbot's suggested messages and specifies they are clickable prompts for visitors. It distinguishes its purpose from siblings by naming the specific resource and connecting to update/remove tools.
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 indicates using the returned id with update_suggested_message or remove_suggested_message, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., get_chatbot or list_chatbots). No context on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-index an existing knowledge source to pick up its latest content.
| Name | Required | Description | Default |
|---|---|---|---|
| source_id | Yes | The source id (from list_sources). | |
| chatbot_id | Yes | The chatbot id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are empty, so description must disclose behaviors. It indicates a mutation ('Re-index') but does not detail potential side effects, authorization needs, or whether it is destructive. Lacks crucial behavioral context.
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?
Single, concise sentence that front-loads the verb and resource. Every word contributes meaning with no redundancy.
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 mutation tool with no output schema and no annotations, the description is adequate but incomplete. It does not mention return values or confirm success indicators.
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% with clear parameter descriptions. The tool description adds no extra meaning beyond the schema, so baseline score 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?
Description clearly states the action ('Re-index'), the resource ('existing knowledge source'), and the purpose ('pick up its latest content'). It distinguishes from sibling tools like 'add_source' and 'list_sources'.
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?
No explicit guidance on when to use this tool versus alternatives. It implies usage when a source needs refreshing, but does not mention prerequisites (e.g., source must exist) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a suggested message from a chatbot. Get the id from list_suggested_messages.
| Name | Required | Description | Default |
|---|---|---|---|
| chatbot_id | Yes | The chatbot id. | |
| suggested_message_id | Yes | The suggested message id (from list_suggested_messages). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With empty annotations, the description carries the full burden of behavioral disclosure. It only says 'Remove a suggested message' without revealing whether the action is permanent, whether permissions are required, or if there are side effects. This is a significant gap for a destructive operation.
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 two sentences, front-loaded with the main action, and contains no filler or repetition. 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 simple two-parameter removal tool, the schema and description cover the essentials: what the tool does and how to obtain the id. However, the lack of annotations and absence of any note about permanence or side effects leaves a gap, making it minimally complete.
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 schema already documents both parameters at 100% coverage. The description adds value by instructing the user to get suggested_message_id from list_suggested_messages, which clarifies the source of the id and reduces ambiguity.
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 clearly states 'Remove a suggested message from a chatbot' with a specific verb (remove), resource (suggested message), and scope (from a chatbot). This distinguishes it from sibling tools like add_suggested_message and update_suggested_message.
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 provides a clear prerequisite: 'Get the id from list_suggested_messages,' which guides the user on how to obtain the required id. However, it does not explicitly mention when not to use this tool or compare it to alternatives like update_suggested_message.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a chatbot's settings. Only the fields you pass are changed. Call get_chatbot first to see allowed_models before changing gpt_model.
| Name | Required | Description | Default |
|---|---|---|---|
| topK | No | Retrieved-chunk count 1-3. | |
| gpt_model | No | LLM model id. Must be one of the chatbot's allowed_models. | |
| chatbot_id | Yes | The chatbot id. | |
| temperature | No | Sampling temperature 0-2. | |
| history_count | No | Conversation history turns 0-10. | |
| default_answer | No | Fallback answer when the bot cannot answer. | |
| welcome_message | No | Welcome message (max 500 chars). Separate multiple bubbles with a blank line. | |
| escalations_email | No | Semicolon-separated email addresses notified on escalation. | |
| enable_escalations | No | Turn human-handoff escalations on/off. | |
| enable_lead_capture | No | Turn the lead-capture form on/off. | |
| instructions_prompt | No | System/instructions prompt (max 20000 chars). | |
| lead_capture_fields | No | Lead-capture field definitions {type,name,required,enabled,order}. Required when enabling lead capture. | |
| escalate_message_threshold | No | Messages before a human handoff is offered (1-10). | |
| enable_escalations_round_robin | No | Rotate escalation emails round-robin across the addresses. | |
| enable_escalations_notification | No | Email a notification when a conversation escalates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions the partial update behavior but lacks details on authentication, rate limits, response format, or error handling. The disclosure is minimal beyond what the schema already provides.
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, front-loaded with the key point of partial update. Every word earns its place. No fluff.
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?
Given 15 parameters, no output schema, and no annotations, the description is sparse. It explains the partial update and one prerequisite but omits return values, error conditions, and other behavioral context needed for a comprehensive update tool.
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 is 3. The description does not add meaningful semantic information beyond the schema descriptions; it only reiterates the requirement for gpt_model consistency, which is already in 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 clearly states the tool updates chatbot settings and uses a partial update pattern ('Only the fields you pass are changed'). It distinguishes from sibling tools like get_chatbot or other update tools.
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 explicitly advises calling get_chatbot first to check allowed_models before changing gpt_model, providing a specific usage guideline. It does not explicitly list when not to use or alternative tools, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing suggested message. Only the fields you pass are changed. Get the id from list_suggested_messages.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The button label (max 100). | |
| type | No | ai, redirect, email, intercom, follow_up, follow_up_link, follow_up_email, escalate. | |
| action | No | A URL or email (max 200). | |
| prompt | No | The message sent when clicked (max 200). | |
| chatbot_id | Yes | The chatbot id. | |
| suggested_message_id | Yes | The suggested message id (from list_suggested_messages). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that the tool performs a partial update (only passed fields change). It does not mention side effects, permissions, or idempotency. For a mutation tool, this is minimal but acceptable.
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 with no waste. The first sentence states the action, the second adds important nuance and a usage tip. 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?
With no output schema, the description does not explain the return value. It covers the essential behavior (update existing message, partial update) but lacks details on response format or error conditions. Given the tool's simplicity, it is adequate but not complete.
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% with detailed field descriptions. The description adds value by clarifying partial update semantics and providing context for the suggested_message_id parameter ('Get the id from list_suggested_messages').
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 clearly states the verb 'update' and the resource 'existing suggested message'. It also distinguishes from list_suggested_messages by referencing how to get the ID, and from add_suggested_message by implication (create vs update).
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 provides clear guidance: use to update an existing suggested message, and retrieve the ID from list_suggested_messages. It also notes that only passed fields are changed (partial update). However, it does not explicitly state when to use this tool versus alternatives like add_suggested_message, but the context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set an inbox thread status. Use "archived" to mark a thread as done. Allowed: read, unread, archived, priority, snooze.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | read | unread | archived | priority | snooze. "archived" = done. | |
| chatbot_id | Yes | The chatbot id. | |
| visitor_id | Yes | The thread/visitor id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It only states the basic action without mentioning side effects, idempotency, error handling, or permissions, leaving gaps in transparency.
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 concise at two sentences, with no wasted words. It could be slightly more structured, but it is efficient and front-loaded.
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?
Given no output schema and empty annotations, the description lacks return value information, prerequisites, and potential effects. For a mutation tool, this is insufficiently complete.
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 input schema covers all three parameters with descriptions, so the baseline is 3. The description adds a hint about 'archived' meaning done, providing moderate additional semantic value 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 clearly states the action ('Set an inbox thread status') and the resource ('inbox thread'). It lists allowed statuses and hints that 'archived' marks as done, making it specific and distinct from sibling tools.
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 provides a hint to use 'archived' for marking done, but does not explicitly state when to avoid the tool or compare with alternatives. Since no sibling tool performs a similar function, the context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
remove_suggested_messageadd_sourceadd_suggested_messageget_chatbotget_chatbot_analyticsget_chatbot_insightsget_thread_messageslist_chatbotslist_inbox_threadslist_leadslist_sourceslist_suggested_messagesrecrawl_sourceupdate_chatbot_settingsupdate_suggested_messageupdate_thread_status
Add one secure layer between your agents and this server.