Autonomous AI customer support engine with 81 FastMCP tools, website crawling, WooCommerce sync, calendar booking, and live human takeover.
Scored across 81 tools
The surface spans many subdomains, and several tools overlap in intent: test_chatbot_reply vs test_rag_retrieval, analyze_chatbot vs get_bot_performance_scorecard, and multiple knowledge-ingestion paths (add_chatbot_knowledge, crawl_website_knowledge, upload_knowledge_document, sync_cloud_storage, create_help_center_article). Detailed descriptions help, but with 81 tools an agent can still misselect between analytics, testing, and knowledge variants.
Nearly all tools follow a predictable snake_case verb_noun pattern (list_chatbots, create_campaign, get_knowledge_sync_status, configure_guardrails). The main exception is human_agent_takeover, which is a noun phrase rather than a verb-led tool name.
81 tools is far beyond a practical MCP surface; even for a broad chatbot platform it forces agents to search a very large action space and increases selection errors. The server would benefit from grouping or narrowing tools around core workflows.
Core CRUD and lifecycle coverage is strong for chatbots, knowledge sources, help center content, campaigns, API keys, webhooks, and integrations. Some subdomains are only partially covered (leads list/export only, meetings list only, conversation notes add/list only), but these are minor gaps agents can generally work around.
Add a text snippet or Q&A document to a chatbot's knowledge base.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| bot_id | Yes | ||
| content | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosure. It indicates a mutation ('add') but says nothing about permissions, whether indexing is synchronous, limits on content size, or what happens if a knowledge source with the same name already exists.
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. Every word contributes to the stated purpose, and the accepted content types are mentioned immediately.
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?
There are no annotations, no output schema, and zero schema description coverage, yet the description is only one sentence. For a three-parameter mutation tool, it should clarify required parameters, effects on the knowledge base, and how this differs from the related upload and crawl tools.
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 0%: the parameters bot_id, name, and content are only labeled with titles. The description gives a vague hint that content is a text snippet or Q&A document and that bot_id targets a chatbot, but it never explains the role of 'name' or any format expectations, so it does not compensate for the missing schema documentation.
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 clear verb+resource (add knowledge to a chatbot) and distinguishes the accepted content types (text snippet or Q&A document). It does not explicitly name or differentiate from the close sibling upload_knowledge_document, so it falls 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 phrase 'text snippet or Q&A document' implies this is for inline text rather than file uploads, which gives some usage guidance. However, it never states when to use this versus upload_knowledge_document, crawl_website_knowledge, or sync_cloud_storage, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a private agent note to a conversation. Never sent to the visitor - for other human agents working the inbox.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| bot_id | Yes | ||
| session_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that the note is private and never delivered to the visitor, which is the key behavioral trait, but it says nothing about permissions, whether notes are append-only, ordering, or what the call returns.
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 immediately followed by the visibility constraint. Nothing is redundant or padding.
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?
This is a mutation tool with no annotations, no output schema, and fully undocumented parameters. The description covers visibility but omits who can write notes, how the conversation is targeted via bot_id/session_id, and any side effects an agent would want before calling it.
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 0% for all three required parameters. The description implies what 'note' contains but gives no meaning for bot_id or session_id, nor how to identify the target conversation, so it fails to compensate for the schema gap.
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 ('Add a private agent note to a conversation') and clarifies the visibility scope. It implicitly contrasts with the sibling send_agent_message by saying the note is never sent to the visitor, but it doesn't name that sibling outright.
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 'for other human agents working the inbox' clause hints at the internal-collaboration use case, so usage is inferable. There is no explicit when-to-use/when-not or named alternative such as send_agent_message or list_conversation_notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get usage analytics: message counts, visitor sessions, and leads captured. Optionally filter to activity at or after since (ISO 8601 datetime).
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | ||
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden. It does disclose the metric categories returned and that filtering is inclusive ('at or after'), which is useful, but it omits the default aggregation window when `since` is null, whether counts are totals or per-period, and any permission or rate-limit 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 tight sentences with the returned metrics front-loaded and the optional filter second. No redundant restatement of the tool name and 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 two-parameter read tool with no annotations and no output schema, the definition is serviceable but leaves real gaps: the default time scope when `since` is omitted, what `bot_id` must reference, and the shape/granularity of the returned aggregates are all unspecified.
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 0%, so the description must compensate. It does well for `since`, specifying ISO 8601 format and inclusive semantics that the bare schema lacks, but `bot_id` — the required parameter — is never mentioned or explained anywhere.
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 usage analytics') and then enumerates the exact metrics returned: message counts, visitor sessions, and leads captured. This distinguishes it from metric-specific siblings like get_feedback_and_csat or analyze_sentiment_trends, though it never explicitly names those alternatives.
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 only guidance given is how to use the optional filter, not when to choose this tool over the many neighboring analytics tools (get_bot_performance_scorecard, get_campaign_analytics, analyze_sentiment_trends). No exclusions, no preconditions, no indication of what question this tool answers versus its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform NLP sentiment analysis across recent visitor chat interactions.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| sample_size | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries the full burden of behavioral disclosure. It says sentiment analysis is performed over recent visitor chats, but does not state whether the operation is read-only, what 'recent' means, how sample_size affects results, or whether results are aggregate or per-conversation.
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 single sentence is front-loaded and waste-free, but it is under-specified rather than effectively concise. The brevity leaves key operational details absent.
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 tool with two parameters, no annotations, no output schema, and 0% schema description coverage, the description is too thin. It does not explain the time window, aggregation behavior, or what the sentiment analysis returns.
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 0%, so the description must compensate for undocumented parameters. It mentions no parameters at all, leaving bot_id and sample_size—including the default of 50—entirely unexplained.
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 uses a specific verb and resource: 'Perform NLP sentiment analysis across recent visitor chat interactions.' It clearly distinguishes itself from chatbot configuration or conversation listing tools, though it does not explicitly contrast with analytics siblings like get_feedback_and_csat or analyze_chatbot.
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 explicit guidance on when to use this tool versus alternatives such as get_feedback_and_csat, get_bot_performance_scorecard, or analyze_chatbot. The phrase 'recent visitor chat interactions' implies an analysis use case, but no exclusions, prerequisites, or decision criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate widget WCAG contrast ratios, mobile ergonomics, and microcopy.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Evaluate' implies a read-only analysis, but the description does not state whether it mutates data, what permissions are needed, or what kind of output is produced. Beyond naming the evaluation dimensions, behavioral context is minimal.
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 sentence that is front-loaded with the verb and enumerates the assessed dimensions without any 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?
With no annotations and no output schema, the description should explain return values and preconditions, but it does neither. It also omits any explanation of the required bot_id parameter, leaving an agent uncertain about what to expect from the call.
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 single parameter bot_id has 0% schema description coverage, and the description does not mention it at all. The parameter name is reasonably self-explanatory, but the description provides no additional meaning about scope, format, or how it relates to the analysis.
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 uses a specific verb ('Evaluate') and names the resource plus three concrete assessment areas (WCAG contrast ratios, mobile ergonomics, microcopy). This is clearer than a generic 'analyze' tool, though it doesn't explicitly distinguish itself from siblings like customize_widget_styling or preview_widget_html.
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 states what is evaluated but gives no guidance on when to use this tool versus alternatives such as customize_widget_styling or preview_widget_html. There is also no mention of prerequisites or when this analysis is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clone an existing chatbot into a new bot instance.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| new_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the tool clones a chatbot into a new instance but does not clarify what gets copied (knowledge, settings, instructions), whether the new bot is independent, what permissions are required, or what the result looks like. For a mutation tool, this is a significant gap.
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, front-loaded sentence with no wasted words. It is compact and easy to parse, though it sacrifices completeness for brevity.
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 the absence of annotations, output schema, and parameter descriptions, the description is too thin. For a mutation tool that clones a chatbot, an agent needs to know what is duplicated, whether the clone is immediately active, and any side effects or requirements.
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 0%, and the description adds no meaning beyond the parameter names. It doesn't explain that bot_id identifies the source chatbot or that new_name must be unique or have constraints. The parameter names are intuitive, but the description provides no compensating detail.
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 (clone) and resource (chatbot), making the core action clear. However, it does not differentiate the tool from siblings like create_chatbot or update_chatbot, so an agent cannot tell from the description alone why it should clone rather than create.
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 creating a new chatbot from scratch or updating an existing one. No prerequisites, constraints, or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure Bring-Your-Own-Key (OpenAI, Anthropic, OpenRouter) to minimize token costs.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| api_key | Yes | ||
| provider | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and discloses almost nothing. It does not say whether the API key is validated, stored encrypted, or overwrites prior configuration, nor what permissions are required or what happens on an invalid key — critical gaps for a tool that accepts a secret credential.
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 provider list and cost rationale both carry information. It is efficient rather than padded, though it is arguably too terse for the operation's sensitivity.
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?
Three required parameters, one of them a secret, with no annotations and no output schema, means the description is the only source of behavioral guidance — and it supplies none. An agent cannot tell the effect on existing configuration, error behavior, or return value from this definition.
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 0% — all three parameters have only bare titles. The description does add real value by enumerating valid provider values (OpenAI, Anthropic, OpenRouter), but says nothing about api_key format/validation or what bot_id refers to. Only one of three parameters is effectively compensated for.
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 verb ('Configure') and a resource ('Bring-Your-Own-Key') and names the three supported providers, which is more than a tautology. However, it never says the configuration is scoped to a specific bot or that credentials are being stored, so the actual object of the action is only inferable from the schema. No sibling handles BYOK, so there is nothing to differentiate against.
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 'to minimize token costs' hints at a motivation but gives no when-to-use condition, no prerequisites (e.g. account plan, existing key rotation), and no alternatives such as updating a bot through update_chatbot. An agent must guess whether this replaces or supplements existing provider settings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure Google Calendar/Outlook/Office365 for direct in-chat meeting scheduling.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| enabled | No | ||
| provider | No | google_calendar | |
| timezone | No | UTC | |
| meeting_duration_minutes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It never states whether this is a create-or-update/upsert, whether it overwrites existing calendar settings, whether an external authorization handshake is required, or whether disabling (enabled=false) revokes stored credentials. For a configuration mutation with five parameters, that is a significant gap.
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?
It is a single well-formed sentence with no filler and the purpose is front-loaded. However, the brevity reflects under-specification rather than discipline — every sentence earns its place only because there is just one.
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 five parameters, 0% schema coverage, no annotations, and no output schema, an agent has almost nothing to reason about: which provider strings are valid, what timezone format is accepted, whether the call is idempotent, and what a successful response returns are all unstated. The description does not fill any of these gaps.
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 0%, so the description must compensate and largely does not: bot_id, enabled, timezone, and meeting_duration_minutes are never mentioned. The only real contribution is naming provider values, but it's ambiguous whether 'Outlook' maps to 'outlook' or 'office365' in the parameter, which is the one place it could have helped most.
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 (Configure) and resource (calendar integration), and enumerates the supported providers (Google Calendar/Outlook/Office365) plus the downstream outcome (in-chat meeting scheduling). It doesn't distinguish this from the many other configure_* siblings, though the resource name is different enough that confusion is unlikely.
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 statement of when to call this versus the related configuration siblings, no prerequisites (e.g., an existing bot, an OAuth/authorization step, a connected provider account), and no exclusions. The phrase 'for direct in-chat meeting scheduling' hints at the outcome but gives no conditions for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restrict widget embedding strictly to authorized domains.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| allowed_domains | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the intended effect (restricting embedding to authorized domains), but does not say whether the call replaces or appends to an existing allowlist, what permissions are required, what happens to currently unauthorized domains, or whether an empty list blocks all embedding.
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 front-loaded sentence with no wasted words. It is efficient, though its brevity leaves important semantics unaddressed.
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 mutation tool with two required parameters, no annotations, no output schema, and 0% schema description coverage, the description is too thin. It should explain the replacement behavior, domain format, bot scoping, and any permission or validation constraints.
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 0%, so the description must compensate for the undocumented parameters. It alludes to 'authorized domains' but does not explain the format (bare domains vs URLs, wildcard support, port handling), and it never mentions the required bot_id parameter.
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: restricting widget embedding to authorized domains. It aligns cleanly with the tool name configure_domain_allowlist and is distinguishable from sibling tools like customize_widget_styling or generate_embed_code. However, it does not explicitly name those alternatives or clarify that it configures the allowlist for a specific bot.
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 no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of when not to use it. The agent must infer usage from the purpose statement alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set strict RAG grounding boundaries, blocked topics, and safety fallback messages.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| strict_mode | No | ||
| blocked_topics | No | ||
| blocked_keywords | No | ||
| fallback_message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies mutation but does not state permissions required, whether existing guardrails are overwritten, how defaults like strict_mode=true behave, or what happens when blocked_topics/blocked_keywords are null.
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 well-formed sentence with no filler, and the core action is front-loaded. Every word contributes to the stated 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?
This is a mutation/configuration tool with five parameters, no annotations, and no output schema. The description is far too sparse to tell an agent how to invoke it safely or correctly, especially regarding required bot_id, defaults, null handling, and overwrite semantics.
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 0%, so the description must compensate for five undocumented parameters. It references strict grounding, blocked topics, and fallback messages, but omits the required bot_id, blocked_keywords, and any format or interaction details for these parameters.
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 uses a specific verb ('Set') with a specific resource ('guardrails') and names the main configuration areas: RAG grounding boundaries, blocked topics, and fallback messages. It is clear what the tool does, though it does not explicitly distinguish itself from related configuration siblings such as update_chatbot_instructions.
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, no prerequisites, and no exclusions. The closest thing to guidance is the implied context that it configures safety behavior, but an agent must infer all usage conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure in-chat lead capture: whether it's on and which fields (name/email/phone) are required before a lead is captured.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| enabled | No | ||
| collect_name | No | ||
| collect_email | No | ||
| collect_phone | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for a mutation tool. It does not disclose whether this is a full replace or a partial update of the existing config, what happens to already-collected fields when capture is disabled, or whether elevated permissions are needed.
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, using the colon to enumerate the two dimensions of the setting. It is dense but earns its words; slightly more structure would help disambiguate the defaults.
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?
Five parameters, zero schema descriptions, no annotations, and no output schema: the description should explain update semantics and defaults but does not. An agent could invoke it but cannot predict whether omitting a boolean resets it or leaves it untouched.
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 0%, so the description must compensate — and it partly does, mapping 'whether it's on' to enabled and 'which fields (name/email/phone) are required' to the three collect_* booleans. However, bot_id is unmentioned and the partial-update semantics of omitting optional booleans (which carry defaults) are not explained.
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 ('Configure in-chat lead capture') and names the actual settings controlled (on/off plus required fields), so an agent knows exactly what the call changes. No sibling tool in the list overlaps in function, so the lack of explicit sibling differentiation costs little.
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 never says when to reach for this tool versus related ones (e.g., list_leads/export_leads for reading captured leads) or what prerequisites exist. It gives only a bare statement of function with no conditions, exclusions, or sequencing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the admin email addresses that receive lead/escalation alert emails. For Slack/Discord/custom event alerts, use create_webhook_subscription instead.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| admin_emails | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries full burden. It implies a mutation but doesn't disclose whether existing emails are replaced or appended, whether permissions are required, or what happens on invalid addresses.
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 zero waste; the purpose is front-loaded and the alternative follows immediately.
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 core purpose and the alternative are covered, and no output schema exists to require return-value explanation. However, for a mutation tool with no annotations and zero parameter documentation, the description leaves meaningful gaps around scope and effect semantics.
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 0%, so the description must compensate. It explains admin_emails loosely as recipient addresses but says nothing about email format, multiple addresses, or the role of bot_id, leaving half the parameters undocumented.
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 ('Set') and resource ('admin email addresses that receive lead/escalation alert emails'), making the outcome unambiguous. It doesn't need heavy sibling differentiation since the scope is narrow, though it could name the bot scope more 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?
Explicitly names the alternative (create_webhook_subscription) and the condition that selects it (Slack/Discord/custom event alerts). This routes the agent away from misuse, though it doesn't state prerequisites like bot admin permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure a Slack incoming webhook to receive real-time notifications for human handoff or negative sentiment.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| webhook_url | Yes | ||
| channel_name | No | #support |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the effect (real-time Slack notifications on escalation events) but says nothing about required Slack permissions, whether an existing webhook config is overwritten, validation of the URL, or failure behavior for a configuration mutation.
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?
One sentence, front-loaded with the action and resource, with no filler. It is arguably too terse for a mutation tool, but nothing in it is wasted.
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?
A configuration/mutation tool with no annotations, no output schema, and zero parameter descriptions needs the description to fill in scope, permissions, and parameter meaning. It covers only the high-level purpose, leaving the agent without enough to invoke it 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 description coverage is 0% — all three properties are bare titles. The description only hints at webhook_url ('Slack incoming webhook'); bot_id and channel_name (default '#support') are never explained, so an agent gets no added meaning 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?
States a specific verb (configure) and resource (Slack incoming webhook), plus the triggering events (human handoff, negative sentiment). This separates it from generic siblings like configure_notifications or create_webhook_subscription, though it doesn't explicitly name those alternatives.
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 trigger conditions ('human handoff or negative sentiment') imply when this tool is relevant, but there is no explicit guidance on when to pick it over configure_notifications or create_webhook_subscription, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure or toggle the LiveKit voice agent for a chatbot.
- enabled: enable or disable voice sessions for this bot.
- mode: 'pipeline' (modular STT + LLM + TTS) or 'realtime' (end-to-end multimodal audio).
- visualizer: visual audio representation ('wave', 'bar', 'grid', 'radial', 'aura').
- welcome_message: first message spoken when a visitor starts a voice session.
- expression_enabled: enable facial/visual pitch animations.
- realtime_provider: 'google', 'openai', 'azure', 'aws', 'nvidia', 'phonic', 'spacexai', 'ultravox'.
- llm_provider: 'google', 'livekit-inference', 'openai', 'anthropic', 'openrouter'.
- stt_provider: 'google', 'livekit-inference', 'deepgram', 'assemblyai', 'soniox', 'cartesia', 'openai'.
- tts_provider: 'google', 'livekit-inference', 'cartesia', 'deepgram', 'elevenlabs', 'openai', 'fishaudio'.
- tts_voice: voice name / voice ID (e.g. 'Kore', 'Puck', 'alloy', 'echo', etc.).
- max_duration_minutes: maximum voice conversation limit (1-60 mins).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| bot_id | Yes | ||
| enabled | No | ||
| llm_model | No | ||
| stt_model | No | ||
| tts_model | No | ||
| tts_voice | No | ||
| agent_name | No | ||
| visualizer | No | ||
| llm_api_key | No | ||
| stt_api_key | No | ||
| tts_api_key | No | ||
| llm_provider | No | ||
| stt_language | No | ||
| stt_provider | No | ||
| tts_provider | No | ||
| realtime_model | No | ||
| welcome_message | No | ||
| realtime_api_key | No | ||
| realtime_provider | No | ||
| expression_enabled | No | ||
| max_duration_minutes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral burden, and it leaves key questions open: are unset (null-defaulted) parameters preserved or reset to defaults, does this require an existing agent, are changes immediately live or does the agent need a restart, and how are API keys stored. It does at least convey mutation semantics and a hard ceiling ('1-60 mins') via max_duration_minutes.
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 one-line purpose is front-loaded and each bullet is a single dense line pairing a parameter name with its allowed values or effect. Given 22 parameters, the length is proportionate; minor waste only in listing provider names without saying which model families pair with them.
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 22-parameter mutation tool with no annotations and no output schema, the description is under-specified: it never explains partial-update semantics (all params are optional with null defaults), never explains mode-dependent parameters, and never says what the tool returns or how configuration errors surface. An agent could construct a call but could easily clobber settings or omit required provider/model pairings.
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 0% across 22 parameters, but the description supplies genuine meaning for roughly half of them, including option lists for mode, visualizer, and the four provider parameters that the schema leaves as bare strings. However, 10+ parameters — bot_id, llm_model, stt_model, tts_model, realtime_model, agent_name, stt_language, and the three api_key fields — get no explanation, and the api_key fields in particular need guidance on when they are required versus inherited from configure_byok.
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 opens with a specific verb and resource ('Configure or toggle the LiveKit voice agent') and scopes it ('for a chatbot'), and the bullet list makes clear this is the write-side counterpart to the read-only voice config sibling. It stops short of naming get_voice_agent_config as the inspection route, but the purpose itself 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?
Usage is only implied by the parameter enumeration: an agent can infer this is the tool for changing voice settings, but nothing states when to use it versus get_voice_agent_config, whether it must be called after create_chatbot, or which parameters apply only in 'realtime' vs 'pipeline' mode. No prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect official WhatsApp Business Cloud API to this chatbot.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| access_token | Yes | ||
| phone_number_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden, but it says nothing about authentication requirements, whether existing WhatsApp configuration is replaced, whether the connection is validated immediately, or what side effects occur. It simply states the connection objective without disclosing any operational 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?
The single sentence is front-loaded and contains no filler, making it structurally efficient. However, its brevity contributes to under-specification rather than appropriately sized conciseness for a three-parameter configuration tool.
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 annotations, no output schema, and 0% parameter description coverage, the description should provide substantially more setup context. It identifies the integration but leaves the agent without enough information to invoke the tool 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 description coverage is 0%, and all three required parameters (bot_id, phone_number_id, access_token) are undocumented in both the schema and the description. The description provides no explanation of what these identifiers are or where they come from.
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 clear verb and resource: connect the official WhatsApp Business Cloud API to this chatbot. It identifies the integration target precisely, though it does not explicitly distinguish this tool from sibling integrations like configure_slack_escalation or configure_woocommerce.
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, no prerequisites, and no exclusions. The intended use is only implied by the tool name and the phrase 'Connect official WhatsApp Business Cloud API.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect a WooCommerce store to the chatbot for automated product RAG catalog queries.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| store_url | Yes | ||
| consumer_key | Yes | ||
| consumer_secret | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not say whether connecting replaces an existing store configuration, whether credentials are validated on call, what WooCommerce permission scope the keys require, or whether the operation is idempotent.
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 efficient sentence with the purpose front-loaded and no filler. Brevity is appropriate, though the space saved is not reinvested in any operational detail.
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 four-required-parameter tool handling secret credentials with zero schema descriptions, no annotations, and no output schema, the description is far too thin. It should cover credential sourcing, re-configuration behavior, and expected result of a successful connect.
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 0% across four required parameters, and the description only vaguely implies bot_id and store_url. It never explains that consumer_key/consumer_secret are WooCommerce REST API credentials or what format store_url should take.
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: connecting a WooCommerce store to the chatbot for product RAG catalog queries. It is distinguishable from mutation siblings like sync_woocommerce_products, but it never names those siblings explicitly to clarify the setup-vs-sync boundary.
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 when-to-use guidance, no prerequisites, and no mention of alternatives such as sync_woocommerce_products or get_woocommerce_store_status. The agent must infer that this is the initial setup step and that syncing happens elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a URL and index its content as a knowledge source (same crawl used by the dashboard's URL-import and the Developer API's POST /api/v1/knowledge).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about whether the crawl is synchronous or async, what happens on re-crawling an existing URL (duplicate/overwrite), what permissions or auth are required, or how long indexing takes. The dashboard/API equivalence is mildly useful context but isn't behavioral disclosure. For an ingestion mutation this is a notable gap.
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?
One compact sentence with the action front-loaded and detail confined to a parenthetical. Nothing is padded, though the parenthetical spends its words on tooling lineage rather than on the parameter and behavior information the agent actually needs.
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-required-parameter mutation tool with no annotations, no output schema, and 0% parameter coverage, the description is thin. It omits bot_id entirely, doesn't indicate how to verify the result (e.g. via get_knowledge_sync_status or list_knowledge_sources), and gives no expectations about timing or failure modes.
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 0% and the description only implicitly covers 'url' via 'Fetch a URL'. The required bot_id — which bot/chhatbot the knowledge attaches to — is never mentioned in the description or the schema, leaving a critical required parameter completely undocumented.
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?
Names a specific action pair (fetch a URL, index as knowledge source) and frames the outcome clearly as knowledge ingestion. It does not distinguish itself from sibling ingestion tools like upload_knowledge_document or add_chatbot_knowledge, so an agent can't route between them from the description alone. The purpose itself 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?
'Index its content as a knowledge source' implies the when (importing web content into a bot's knowledge base), but there are no explicit when-not conditions and no alternatives named. The parenthetical compares it to a dashboard feature and an API endpoint rather than to sibling tools, which doesn't help the agent choose between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new bot-scoped API key (chatty_sk_...). The raw key is returned once.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | MCP API Key | |
| bot_id | Yes | ||
| scopes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the critical one-time-secret behavior ('raw key is returned once'), which is a meaningful mutation trait. It omits permission requirements, whether scopes default to unrestricted access when null, and irreversibility/lifecycle details.
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 tight sentences with zero filler, and the essential fact (one-time key return) is front-loaded alongside the action.
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 security-sensitive creation tool with no annotations, no output schema, and zero schema documentation, the description is too thin. It should at minimum explain scopes semantics, default behavior when scopes is null, and required permissions to be safely callable.
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 0% across three parameters, so the description must compensate and it largely does not. 'Bot-scoped' loosely implies bot_id, but the optional 'name' parameter and especially 'scopes' (nullable, default null) are never explained, leaving the agent guessing at the most security-relevant parameter.
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 ('Create a new bot-scoped API key') and even shows the key prefix format. The create verb naturally separates it from sibling list_api_keys and revoke_api_key, 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?
'The raw key is returned once' implicitly tells the agent to persist the value immediately, which is real usage guidance. However, there is no explicit when-to-use framing, no prerequisites (admin permissions, bot ownership), and no pointer to revoke_api_key for lifecycle management.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a proactive announcement or visitor engagement campaign.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| bot_id | Yes | ||
| is_active | No | ||
| trigger_type | No | time_on_page | |
| url_patterns | No | ||
| campaign_type | No | chat_bubble | |
| trigger_value | No | ||
| target_devices | No | ||
| message_content | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden and delivers almost none of it: it doesn't say the campaign is created active by default (is_active defaults true), that it will begin firing on live traffic immediately, whether it can be edited/deleted afterward, or what permissions/plan are required. For a side-effectful creation tool this is a substantial gap.
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, and the verb/resource lead. Its brevity is a deficiency in coverage rather than a structural flaw, but there is no structure to speak of beyond the one clause.
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 9 parameters, zero schema descriptions, no annotations, and no output schema, the description should be doing heavy lifting and instead says nothing about configuration, defaults, or result. It is not remotely sufficient for an agent to call this correctly.
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 0% across 9 parameters, so the schema gives only bare titles and defaults. The description compensates for none of it — trigger_type, trigger_value, campaign_type, url_patterns, and target_devices are entirely unexplained, leaving the agent to guess accepted values and semantics.
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 (Create) plus the resource (campaign) and qualifies the two modes — proactive announcement vs. visitor engagement. An agent can distinguish it from list_campaigns, update_campaign, and delete_campaign, though it doesn't clarify how it differs from the create_* siblings like create_webhook_subscription.
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 create a campaign versus other engagement mechanisms, no prerequisites (e.g. the bot_id must reference an existing chatbot), and no mention of related siblings such as update_campaign or get_campaign_analytics for follow-up. The agent must infer all of this from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Chatty AI chatbot with initial identity and settings.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| primary_color | No | ||
| selected_model | No | ||
| welcome_message | No | ||
| response_language | No | ||
| system_instructions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and mostly fails it: it does not say whether unspecified optional fields are nulled or given server defaults, whether creation requires an admin role, whether the bot is live immediately, or how to reverse it. "Initial identity and settings" is the only behavioral hint, weakly signaling that later changes go through update_chatbot.
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 or redundancy. It is efficient but under-informative rather than padded, and it never gets more specific than its opening clause.
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 6-parameter mutation tool with zero annotation coverage, zero schema descriptions, and no output schema, the description is far too thin. An agent cannot tell what a successful call yields, what defaults apply, or how creation relates to the large set of configuration siblings.
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 0% across 6 parameters, so the description must compensate and does not. "Identity and settings" loosely gestures at name/color/welcome_message versus model/language/instructions, but no parameter is named or explained, leaving required vs optional semantics and expected formats undocumented.
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 ("Create a new Chatty AI chatbot") plus the scope of what is created ("initial identity and settings"). It is distinct from update_chatbot and clone_chatbot by implication, though it never names those siblings to make the distinction explicit.
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 create versus clone an existing bot, no prerequisites (plan limits, account permissions), and no statement about what happens after creation. The agent must infer usage entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create and publish a Help Center article. Automatically trains the bot's RAG memory so the AI assistant can reference it in chat.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | ||
| tags | No | ||
| title | Yes | ||
| bot_id | Yes | ||
| status | No | published | |
| content | Yes | ||
| subtitle | No | ||
| visibility | No | public | |
| category_id | No | ||
| is_promoted | No | ||
| order_index | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses a non-obvious side effect: the article automatically trains the bot's RAG memory. It does not state whether the operation requires specific permissions, whether re-creating duplicates existing articles, how the default visibility of 'public' affects exposure, or what the response contains.
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 filler, and the core action is front-loaded before the side-effect context. 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 an 11-parameter creation tool with no annotations, no output schema, and 0% parameter description coverage, the description does too little. It should at minimum explain the status, visibility, and category/slug semantics that materially affect the created article, and note the RAG training implications in more detail.
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 has 11 parameters with 0% description coverage, and the description explains none of them: no mention of slug, tags, status, visibility, subtitle, category_id, is_promoted, or order_index. 'Create and publish' only loosely hints at the status parameter. With so many undocumented parameters and defaults that materially affect behavior, the description fails to compensate for the schema gap.
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?
Clearly states a specific verb and resource: 'Create and publish a Help Center article.' This distinguishes it from sibling mutation tools like update_help_center_article and creation tools for other resources such as create_help_center_category. The only slight ambiguity is 'publish,' since status defaults to published but could also be a draft.
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 second sentence implies the use case: create an article so the AI assistant can reference it in chat. However, there is no explicit guidance on when to use this versus update_help_center_article, no mention of prerequisites like bot_id or category_id, and no note that status can be set to non-published.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new category in the bot's Help Center / Knowledge Base.
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | Folder | |
| name | Yes | ||
| slug | No | ||
| bot_id | Yes | ||
| description | No | ||
| order_index | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses almost nothing beyond the fact that it mutates state. It does not say whether names must be unique, whether slug is auto-derived from name when null, how order_index behaves, or what happens on a duplicate/conflict.
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 padding, but its brevity reflects under-specification rather than disciplined economy given the complexity of the operation.
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?
A six-parameter mutation tool with no annotations, no output schema, and no parameter documentation anywhere — the description does nothing to fill the gaps an agent would need in order to call this correctly.
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 0% across six parameters, and the description adds no parameter meaning whatsoever — nothing about slug generation, icon defaults, order_index semantics, or the bot_id scoping requirement. The description fails to compensate for a total schema gap.
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: create a new category in the Help Center / Knowledge Base. The verb distinguishes it from siblings update_help_center_category, delete_help_center_category, and list_help_center_categories, 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 versus updating an existing category, no mention of ordering relative to article creation, and no prerequisites (e.g. whether a category must exist before articles can be filed under it). The agent must infer all of this from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subscribe a URL (Slack/Discord incoming webhook, or any HTTPS endpoint) to real-time bot events. Returns a signing secret used to verify delivered payloads.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| bot_id | Yes | ||
| events | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations the description carries the full burden, and it does add real behavioral value by disclosing that a signing secret is returned and what that secret is for. However, it says nothing about permissions/auth needed, whether subscriptions are idempotent or additive, whether event delivery is retried, or what happens when the URL is unreachable.
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, both earning their place; the primary action leads and the return-value note follows. No filler or restatement of the tool name.
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?
Three required parameters, 0% schema coverage and no output schema. The description covers the endpoint and the return secret but leaves the event vocabulary and bot_id semantics entirely undefined, which is not enough for an agent to construct a valid call without guessing.
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 0%, so the description must compensate and only partially does: it clarifies the 'url' parameter's accepted forms, but 'bot_id' and especially 'events' receive no explanation. The valid event names are the single most important unknown for this call, and neither schema nor description lists them.
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: subscribe a URL to real-time bot events, with the accepted target types (Slack/Discord webhook, any HTTPS endpoint) made explicit. It is clearly distinguishable from list_webhook_subscriptions and delete_webhook_subscription, though it never names them.
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 says what the tool does but gives no when-to-use guidance, no prerequisites (e.g. whether the bot must exist first, whether an endpoint can be subscribed twice), and no reference to sibling tools for inspecting or removing subscriptions. Usage is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Customize widget appearance: colors, avatar/logo, teaser bubble message, conversation-starter chips, custom CSS, and white-label branding.
Per-section colors (independent of primary_color/widget_style - these are the dashboard Customizer's advanced color pickers):
- auto_generate_color_scheme: pass a seed hex (e.g. "#c67139") to derive a full, harmonious 6-section scheme (header, botBubble, userBubble, inputBar, sendBtn, launcher) - same algorithm as the dashboard's own Auto-generate button.
- color_scheme: set/override individual sections directly, e.g. {"header": {"bg": "#111827", "text": "#ffffff"}} - only the sections/fields given are touched, everything else (existing or just auto-generated) is left as-is. Combine both in one call: auto-generate a base scheme, then override just the header.
- clear_color_scheme=true removes it entirely so primary_color/widget_style fully take over again.
If a primary_color/widget_style change doesn't seem to take effect, check the returned color_scheme field - it takes priority over them wherever it's set.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| avatar_url | No | ||
| custom_css | No | ||
| avatar_icon | No | ||
| color_scheme | No | ||
| widget_style | No | ||
| hide_branding | No | ||
| primary_color | No | ||
| teaser_message | No | ||
| header_logo_url | No | ||
| clear_color_scheme | No | ||
| conversation_starters | No | ||
| auto_generate_color_scheme | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden, and it does well for the most complex parameter: it explains that color_scheme merges section by section and field by field, that clear_color_scheme removes the override, and that color_scheme takes priority over primary_color/widget_style. It leaves gaps around update semantics for other fields, permission requirements, and side effects, so it is strong but not complete.
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 front-loaded with the tool's overall purpose and then uses bullets to organize the complex color-scheme semantics. It is relatively long, but most sentences earn their place by explaining non-obvious behavior; there is little wasted text.
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 mutation tool with 13 parameters, no annotations, and no output schema, the description is complete for the color-scheme subsystem but not for the widget-styling tool overall. It does not explain what happens to unspecified fields, how null versus omitted values behave outside color_scheme, or the implications of custom_css and hide_branding.
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 0%, so the description must compensate, and it does add meaningful detail for color_scheme, auto_generate_color_scheme, clear_color_scheme, and the priority relationship with primary_color/widget_style. However, several of the 13 parameters, including avatar_url versus avatar_icon versus header_logo_url, widget_style, hide_branding, and custom_css, receive only broad category mentions rather than parameter-level semantics.
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, 'Customize,' and a clear resource, 'widget appearance,' then enumerates the visual aspects covered: colors, avatar/logo, teaser message, conversation starters, custom CSS, and white-label branding. It does not explicitly distinguish this tool from siblings such as analyze_widget_design or preview_widget_html, but the purpose is otherwise 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?
The description implies usage through its detailed explanation of color_scheme behavior and the note about primary_color/widget_style priority, but it never states when to choose this tool over alternatives like update_chatbot or analyze_widget_design. There are no explicit exclusions or routing guidance for the overall tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a campaign.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| campaign_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It usefully discloses that deletion is permanent, signaling an irreversible destructive action, but it omits permissions required, side effects such as whether associated campaign data is also removed, and whether any confirmation is needed.
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 front-loaded sentence with no wasted words. The destructive qualifier 'Permanently' appears before the resource, which is the most important information for an agent.
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?
This is a destructive mutation tool with no annotations, no output schema, and zero parameter description coverage. One short sentence conveys permanence but leaves out prerequisite context, side effects, and parameter semantics needed for confident invocation.
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 0%, and two parameters are required. The description mentions 'campaign' but does not explain the meaning, format, or relationship of bot_id and campaign_id, so it does not compensate for the schema gap.
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: 'delete' plus 'campaign', with the important qualifier 'Permanently'. This distinguishes it from create_campaign, update_campaign, and list_campaigns by operation, though it does not explicitly name alternatives or clarify the bot/campaign relationship.
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 update_campaign, nor any prerequisites or confirmation steps. The word 'Permanently' implies caution, but no explicit when/when-not conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a chatbot permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and 'permanently' is the one useful disclosure — it flags irreversibility. It says nothing about what collateral data is destroyed (conversations, knowledge sources, embed code, widget config), whether elevated permissions or confirmation are required, or whether the operation can fail on an in-use bot.
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?
One short sentence, front-loaded with the destructive verb, no filler. Its brevity is a virtue on this dimension, though the size reflects under-specification rather than disciplined editing.
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 permanent, irreversible mutation with no annotations, no output schema, and undocumented parameters, the description should cover blast radius and failure modes. None of that is present, so an agent cannot predict consequences of calling it.
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 0%, so the description must explain bot_id, and it does not — no format, no source of the ID, no indication of what happens with an unknown or already-deleted ID. The single parameter is only guessable from its name.
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?
Specific verb (delete) plus resource (chatbot), and 'permanently' adds real scope information beyond the name. It does not distinguish itself from adjacent destructive siblings such as purge_bot_knowledge or delete_knowledge_source, so an agent must infer that this removes the bot object itself.
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 statement of when to use this versus update_chatbot, purge_bot_knowledge, or delete_knowledge_source, and no preconditions (ownership, active-conversation state) before invoking. The agent is left to infer that permanent deletion is the last-resort path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Help Center article and remove its vector embeddings.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| article_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully mentions that vector embeddings are removed, but it does not state whether deletion is permanent, whether it requires specific permissions, or what happens to associated data.
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 front-loaded sentence with no wasted words. It communicates the core action and the notable side effect 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?
This is a destructive mutation tool with no annotations, no output schema, and 0% parameter description coverage. The description notes the vector-embedding side effect but omits irreversibility, authorization requirements, and return behavior, leaving significant gaps for a delete 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 0%, so the input schema provides only parameter names and types with no semantic detail. The description does not explain what bot_id or article_id identify, leaving both parameters essentially undocumented.
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: delete a Help Center article. It also adds a distinguishing side effect, removing vector embeddings, which separates it from sibling article operations like update_help_center_article and get_help_center_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as update_help_center_article or delete_help_center_category. It also omits prerequisites, confirmation requirements, or any warning that this is a destructive action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Help Center category.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| category_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for a destructive mutation, yet it discloses nothing beyond the word "Delete." It does not say whether deletion is irreversible, whether articles inside the category are removed or orphaned, or what permissions/scope bot_id requires.
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 waste, but that brevity comes from under-specification rather than economy. It is appropriately sized only in the sense that there is nothing extraneous to trim.
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?
A destructive tool with no annotations, no output schema, and no parameter documentation needs far more: irreversibility, cascade behavior, and required scope. Almost everything an agent needs to invoke this safely 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 0% for both required parameters. The description only hints at category_id through the noun "category" and says nothing about bot_id (whether it scopes the workspace, must match the category's owner, etc.), so it fails to compensate for the undocumented 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 gives a specific verb and resource ("Delete a Help Center category"), so an agent can tell it mutates a category rather than an article or chatbot. It does not differentiate from siblings such as delete_help_center_article, update_help_center_category, or delete_knowledge_source beyond the noun itself.
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 versus update_help_center_category or delete_help_center_article, and no prerequisites or warnings. The only implied usage is the tautological reading of the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a knowledge source and its vector embeddings.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| source_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations are absent, the description adds critical behavioral context by specifying that the deletion includes both the knowledge source itself and its associated vector embeddings. This defines the extent of the 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 definition is brief, direct, and front-loaded, providing all necessary information in a single, effective sentence without any 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?
While the description adequately defines *what* the tool does, it is incomplete for a destructive operation as it offers no safety warnings, prerequisite checks, or rationale for its existence compared to other maintenance functions.
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 0%, meaning the description must compensate. It does not define what 'bot_id' or 'source_id' represent (e.g., required format, ownership, or purpose), rendering the parameter definitions largely meaningless to the agent without external context.
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 provides a highly specific, action-oriented statement, using the verb 'Delete' and clearly identifying the resource ('knowledge source') and its consequence ('vector embeddings'). This 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?
The description offers no guidance on when to use this tool versus the many similar functions in the sibling set (e.g., list_knowledge_sources or purge_bot_knowledge). It fails to establish context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an event-webhook subscription.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| webhook_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it discloses only that the operation deletes. It says nothing about irreversibility, whether in-flight deliveries stop immediately, whether the call is idempotent, what happens if webhook_id is unknown, or what authorization is needed for the bot_id.
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 short sentence with no wasted words and the resource front-loaded, which is structurally sound. However, the terseness crosses into under-specification for a destructive operation, so it is economical without being adequate.
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 destructive, two-required-parameter mutation with no annotations and no output schema, the description leaves the agent without permanence warnings, parameter meaning, or failure behavior. It is not sufficient to call this tool safely and correctly on its own.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both required parameters (bot_id, webhook_id) have 0% schema description coverage, and the description does not compensate by explaining which bot scope the id belongs to or the expected identifier format. It only repeats the resource name already implied by the tool name.
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 ('Delete') and resource ('event-webhook subscription'), so an agent immediately knows the operation type. It does not differentiate itself from the related create_webhook_subscription / list_webhook_subscriptions siblings or clarify that webhook_id refers to a subscription rather than a bot.
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 versus the sibling webhook tools, no prerequisite conditions (e.g., must the subscription exist, must the bot be paused), and no note that deletion is permanent. The agent must infer everything from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan transcripts for unanswered user queries and cluster missing FAQ topics.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Scan' implies a read-only analysis, but it does not state permissions, scope (all transcripts vs. a date range), whether it modifies knowledge, expected runtime, or rate 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?
The description is a single front-loaded sentence with no filler. Every word contributes to the action and outcome.
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 the absence of annotations, output schema, and parameter documentation, the definition is under-specified. It does not explain what the tool returns, how clusters are represented, or how the scan is scoped, which are important for an agent to invoke it 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 description coverage is 0% and the only parameter, bot_id, is undocumented in both the schema and the tool description. The description never mentions the bot, so an agent must infer that transcripts are scoped to bot_id. The self-explanatory parameter name keeps this from being a 1.
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 uses a specific verb ('Scan') and resource ('transcripts') and states the outcome ('cluster missing FAQ topics'). It distinguishes itself from pure transcript retrieval or sentiment analysis, though it does not explicitly name sibling alternatives.
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 analyze_chatbot, get_feedback_and_csat, or test_rag_retrieval. The use case is implied by the purpose, but no exclusions, prerequisites, or workflow context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export captured leads as JSON (default) or CSV text.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| bot_id | Yes | ||
| format | No | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions JSON default and CSV text output, but does not state whether the operation is read-only, what permissions are required, whether export is scoped by bot_id, how limit behaves, or whether results are paginated.
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 definition is a single front-loaded sentence with no wasted words. It immediately states the action, resource, and available output formats.
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 three parameters, no annotations, no output schema, and 0% schema description coverage, the description is too thin. It does not explain export scope, permissions, return structure, or limit semantics, which an agent would need before invoking it 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 description coverage is 0%, so the description needs to compensate. It clarifies that format accepts JSON or CSV, with JSON as default, but it says nothing meaningful about bot_id scope or the limit parameter, leaving two of three parameters without added semantic guidance.
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: 'Export captured leads', and adds the output formats. It is clear what the tool does, but it does not distinguish this from sibling tools such as list_leads or export_visitor_data.
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 instead of list_leads or other lead-related siblings, and no prerequisites or exclusions are stated. Usage is only implied by the verb 'Export'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GDPR data-portability export: every conversation, session, and lead held for this bot, as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it does disclose the complete data scope (conversations, sessions, leads) and the JSON format, which is useful. It says nothing about volume limits, whether the export is synchronous or a background job, authorization requirements, or rate limiting — meaningful gaps for a bulk data-egress 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?
A single sentence with the purpose, scope, and format front-loaded and no filler. 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 one-parameter read-only export with no output schema and no annotations, the description covers what is exported, for which bot, and in what format. Missing only operational context (size, timing, permissions), which is minor for a simple tool but not trivial for a bulk export.
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 0%, so the schema itself says nothing about bot_id beyond its type. The description partially compensates by indicating the export is scoped to a single bot ('held for this bot'), which ties bot_id to scope, but it never states format expectations or what happens with an invalid bot_id.
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 ('GDPR data-portability export') plus the exact scope ('every conversation, session, and lead held for this bot') and output format (JSON). An agent can distinguish it from list_conversations or list_leads, though it does not name those siblings explicitly to reinforce the bulk-vs-paged distinction.
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 'GDPR data-portability' framing implies when to use it (compliance/portability requests for a whole bot), but there is no explicit when-not guidance, no mention of alternatives like export_leads or list_conversations for narrower needs, and no prerequisites such as permission or admin scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a pre-configured claimable demo chatbot for cold outreach or client handoffs. Returns the unique public /claim/ link, bot_id, and an outreach email pitch.
| Name | Required | Description | Default |
|---|---|---|---|
| target_url | Yes | ||
| target_name | Yes | ||
| primary_color | No | #0f172a | |
| welcome_message | No | ||
| suggested_prompts | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral-disclosure burden. It discloses the return values (public /claim/ link, bot_id, outreach email pitch), which is valuable, but it does not explain permissions, whether the outreach email is sent or merely returned, or what side effects occur during bot creation.
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 brief sentences with no wasted text. The main effect is front-loaded, and the return-value detail follows naturally.
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 five-parameter mutation tool with no annotations and no output schema, the description is substantially incomplete. It names return values but leaves parameter meanings, side effects, and invocation prerequisites unexplained, so an agent would have to guess at key aspects of correct 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?
Schema description coverage is 0% across five parameters, and the description never mentions target_name, target_url, primary_color, welcome_message, or suggested_prompts. With no annotations and no schema descriptions, the definition does nothing to compensate for the documentation gap, leaving the parameters to be inferred from bare titles alone.
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 ('Creates'), a specific resource ('pre-configured claimable demo chatbot'), and a concrete use case ('cold outreach or client handoffs'). It does not explicitly differentiate from the sibling create_chatbot tool, but the claimable-demo framing is distinctive enough for an agent to understand the purpose.
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 usage context: cold outreach or client handoffs. It does not state when not to use it or name alternatives such as create_chatbot for full production bots, so the routing guidance is incomplete but still useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate embed code for HTML, Next.js, WordPress, Shopify, iOS, or Android.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| framework | No | html_script |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet says nothing about side effects, whether the operation is safe/read-only, permission requirements, or whether a published bot is needed. For a generation tool this is low-risk, but the agent still cannot tell whether calling it mutates state or requires specific auth.
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 waste; the verb and platform enumeration come first. Nothing is padded or repeated.
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 is simple (1 required param), but with no annotations, no output schema, and 0% schema coverage, the description should at minimum explain bot_id and what the returned embed code looks like (a string snippet vs. structured object). Neither is covered.
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 0%, so the description must compensate: it does list the framework options (HTML, Next.js, WordPress, Shopify, iOS, Android), which adds real meaning for the 'framework' parameter. However, 'bot_id' is never explained and the listed platform labels don't map to the exact accepted string values (e.g., 'html_script'), leaving a gap.
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 (Generate) and resource (embed code) and enumerates the supported target frameworks, so the agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling get_voice_agent_embed_code or say this is for the chat widget rather than a voice agent, leaving some ambiguity.
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 statement of when to use this tool versus alternatives such as get_voice_agent_embed_code or preview_widget_html, and no prerequisites (e.g., bot must exist/published). The only implied usage is 'call after creating a bot,' which the agent must infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get message credits, active bot counts, and subscription status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It implies a read-only retrieval and lists the data surfaced, which helps, but it says nothing about permission requirements, whether billing endpoints are rate-limited, or freshness of the figures. Adequate but incomplete for a zero-annotation tool.
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 sentence with the verb front-loaded and no filler. Every word maps to a returned data point.
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?
Without an output schema or annotations, the description is the only source of return-value information, and it names only three fields. It omits plan details, usage limits, or renewal dates that a billing tool likely returns, leaving the response shape partially unknown.
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 the baseline is 4. There is nothing for the description to compensate for on the input side.
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 uses a specific verb ('Get') with a concrete resource ('account billing') and enumerates what is returned: message credits, active bot counts, subscription status. No sibling tool covers billing, so it is implicitly distinguishable, though it doesn't explicitly differentiate itself.
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 call this tool, no prerequisites (e.g., admin-only access typical of billing data), and no mention of alternatives. The agent must infer usage entirely from the purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get immutable audit logs of administrative actions and configuration changes.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. 'Immutable' usefully signals a read-only, tamper-evident source, but nothing is said about pagination behavior, ordering, time-range coverage, permission requirements, or response shape for a tool with a user-supplied limit.
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 core noun phrase front-loaded and no filler. It is appropriately sized, though the brevity trades away information the tool needs.
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 2-parameter read tool with no annotations, no output schema, and 0% schema description coverage, the description leaves the agent guessing about required scoping (bot_id), result volume (limit default 50), and what a log entry contains. It is under-specified for the structured-data gaps.
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 0%, so neither 'bot_id' nor 'limit' (default 50) is documented anywhere. The description mentions neither parameter and adds no semantics such as whether the logs are scoped to the bot or what limit actually bounds.
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 ('Get') and resource ('immutable audit logs'), and narrows scope to 'administrative actions and configuration changes', which distinguishes it from nearby log/analytics siblings like get_mailbox_logs. It does not explicitly name an alternative, but the resource is concrete enough to route correctly.
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 statement of when to use this versus alternatives such as get_mailbox_logs or the analytics tools, and no mention of prerequisites or scoping (e.g., that logs are per-bot). Usage is only loosely implied by the word 'audit'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit chatbot performance with an A-F letter grade across 5 core operational pillars: Conversion, Engagement & Deflection, Accuracy, Reliability, and Customer Satisfaction.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden; it does disclose the return shape (an A-F grade broken into five named pillars), which is genuinely useful context. It omits, however, the data window semantics, whether a bot needs minimum traffic to be graded, and what happens for a bot with sparse data.
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?
One front-loaded sentence with no filler; the pillar list earns its space because it previews the response structure. Slightly dense, but 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?
No output schema and no annotations mean the description is the only documentation, and it leaves the two parameters completely unexplained and says nothing about data prerequisites or the grading methodology. Adequate as a one-line pitch, insufficient for correct invocation.
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 0% and the description mentions neither parameter. The critical one, 'days' (default 30), is never explained as the lookback window, so the agent cannot tell what time horizon the grade covers or whether the pillars are weighted over that window.
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?
Uses a specific verb ('Audit') plus a named artifact ('A-F letter grade') and enumerates the five pillars, so the agent knows exactly what comes back. It never names or contrasts the overlapping siblings (analyze_chatbot, get_feedback_and_csat, get_campaign_analytics), so differentiation is left 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?
There is no 'use this when' sentence, no exclusion, and no mention of when to prefer this over analyze_chatbot or get_feedback_and_csat, whose CSAT metric overlaps one of the five pillars. The audit framing only implies usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get performance metrics (impressions, clicks, CTR, conversions) for a campaign.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| campaign_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It never discloses the reporting time window (there is no date parameter at all), whether metrics are aggregated or time-series, data freshness, or required permissions — all critical for an analytics tool. Read-only is only implied by 'Get'.
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 metric list is the most useful part and appears early. It is not padded, though its brevity is also the source of the gaps elsewhere.
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?
No output schema, no annotations, and 0% parameter documentation leave the description as the only source of information, yet it omits the reporting period, response shape, and bot_id's role. For an analytics tool where the time window defines the meaning of the numbers, this is a substantial omission.
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 0% for both parameters. The description names 'campaign', which loosely maps to campaign_id, but bot_id is entirely unexplained and no format, scoping, or relationship between the two IDs is given. With two undocumented params the description must compensate and does not.
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'), a specific resource ('performance metrics'), enumerates the metrics returned (impressions, clicks, CTR, conversions), and scopes them to a campaign. This distinguishes it from get_bot_performance_scorecard and get_help_center_analytics by resource, though it never names those siblings 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 statement of when to use this versus get_bot_performance_scorecard, get_help_center_analytics, or get_dashboard_screenshots, and no prerequisites or exclusions. Only the implicit signal that a campaign_id is needed hints at context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full configuration details for a single chatbot by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full load; it implies a read-only operation and that the response is exhaustive ('full configuration details'). It says nothing about permissions, behavior on an unknown bot_id, or whether instructions/settings are included, all of which matter with zero annotation coverage.
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 resource and scoping constraint appear immediately.
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 one-parameter getter this is thin: there is no output schema, so 'full configuration details' is the agent's only hint about the return value, and that hint is vague about which configuration sections come back.
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 0%, so the one parameter (bot_id) is undocumented in the schema. The phrase 'by ID' at least confirms that bot_id identifies the chatbot, but no format, source, or example of the ID is given.
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?
Specific verb (get) + resource (full configuration details) + scope (a single chatbot by ID, not a list). This cleanly separates it from list_chatbots and create/update_chatbot. It does not, however, distinguish itself from get_chatbot_instructions, which is a near-neighbor that returns a subset of the same object.
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 never states when to reach for this versus siblings such as list_chatbots or get_chatbot_instructions. The agent must infer usage purely from the verb 'Get' and the word 'single'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the current system instructions, guidelines, and prompt persona for a chatbot.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the content categories returned and the word 'current' implies a live read of stored config, but it says nothing about permissions needed, behavior when the bot does not exist or has no custom instructions, or whether defaults are returned. Adequate but thin for a no-annotation tool.
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?
One sentence, front-loaded with the verb and the resource set, with zero filler. Sized appropriately for a simple single-parameter read.
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 retrieval tool with no output schema, the description gives a reasonable inventory of what is fetched but leaves return structure and error behavior unstated. Barely sufficient; an agent knows what it gets but not exactly what it will see.
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 0% for the single parameter, and the description merely says 'for a chatbot' without clarifying whether bot_id is a numeric ID, slug, or name, nor where to obtain it. The description does not compensate for the documentation gap 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?
States a specific verb ('Inspect') and specific resources ('system instructions, guidelines, and prompt persona') tied to a chatbot. This clearly distinguishes it from get_chatbot (general bot record) and update_chatbot_instructions (write path), though the description itself never names 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?
No explicit when-to-use or when-not-to-use guidance is given. The read-only framing ('Inspect the current...') implicitly signals the natural read-before-update pairing with update_chatbot_instructions, but the agent must infer that from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the visual conversation flow graph and automated decision tree for a bot.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden: it implies a read but says nothing about permissions, whether the graph is empty for bots without a visual flow, or what the graph structure contains. Return shape matters here because the tool produces a graph object and there is no output schema.
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?
One sentence, front-loaded with the verb and resource, with no filler. It is efficient, though its brevity comes partly from omitting information the agent needs rather than from tight editing alone.
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?
A read tool with no annotations and no output schema needs the description to convey at least the rough return shape (graph nodes/edges vs. a decision tree) and the bot_id requirement. Neither is present, so an agent knows the purpose but not what to expect back or how to call it correctly.
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 0%, so the single parameter bot_id is undocumented in both schema and description. The description never mentions bot_id, whether it accepts an ID vs a name, or where to obtain it, failing to compensate for the coverage gap.
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 ('Retrieve') and a specific resource ('visual conversation flow graph and automated decision tree') scoped to a bot. This clearly separates it from read siblings like get_chatbot and get_chatbot_instructions, though it never names an alternative 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 statement of when to use this versus get_chatbot_instructions, get_chatbot, or update_conversation_flow; the read/navigate relationship to the update tool is left entirely to inference. Usage is only implied by the word 'Retrieve'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full message transcripts and citations for a conversation session.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| session_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and largely drops it. It implies a read but never states read-only safety, whether access is scoped by bot_id, whether transcripts can be large/paginated, or how citations are 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?
A single tight sentence that front-loads the verb and the returned artifact with no filler. Its brevity is only a slight liability because the tool itself is under-described.
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 tool returning potentially large transcripts with citations, and with no output schema, no annotations, and 0% parameter docs, the description omits return shape, pagination, and access requirements. It is not complete enough to call confidently without opening other resources.
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 0% for two required parameters. The phrase 'for a conversation session' loosely implies session_id, but bot_id is never mentioned and neither parameter's format or scoping is explained, so the description fails to compensate for the schema gap.
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 concrete resources (full message transcripts and citations) scoped to a conversation session, clearly distinguishing it from list_conversations. It stops short of naming a sibling or contrasting the transcript view with get_conversation_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, prerequisites, or alternatives. An agent gets no hint that a session_id must typically be obtained first via list_conversations, nor when this is preferable to other conversation-inspection tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the secure integration contract for passing a logged-in website customer to this bot's widget.
This never returns a signing secret. The customer's own server must mint a short-lived HS256 token from the authenticated login session, then pass that token to window.Chatty.identify().
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden well: it explicitly states this never returns a signing secret and describes the intended server-side HS256 token flow. That is real behavioral context an agent would not otherwise know. It stops short of describing the returned document's exact format, so not a 5.
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 tight sentences, purpose front-loaded, followed by the key security caveat and the intended flow. Zero wasted text.
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 documentation-returning tool with no annotations or output schema, the description explains what the returned contract is for and what it does not contain (a secret). It could better describe the shape of the returned guide, but an agent has enough to call it correctly.
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 single parameter bot_id has 0% schema description coverage, so the description should compensate but does not mention it at all. The parameter is self-evident enough to avoid a lower score, but it adds no meaning 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?
States a specific verb and resource: it returns the secure integration contract for passing a logged-in customer to the widget. An agent can see it is a documentation/guide getter rather than a mutation, distinguishing it from the config siblings. It does not name a specific sibling alternative, keeping it at 4.
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 implied by the described flow (server mints a short-lived HS256 token, then passes it to window.Chatty.identify()), which gives context for when an integrator would call this. However, there is no explicit when/when-not guidance or any named alternative among the many configure_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve genuine high-resolution 4K Retina (3840x2160) production screenshots and metadata for Chatty dashboard modules (Overview, Workspace, Customizer, Knowledge Base, Playground, Inbox, Campaigns, Flow Builder, Leads, Feedback, Map, Meetings, Mailbox, Notifications, Audit Log, Analytics, Embed & Integrate, Voice Agent, MCP, Developer API, Billing, Agent Settings) captured for account katdamayantha@gmail.com.
| Name | Required | Description | Default |
|---|---|---|---|
| tab | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral burden and largely fails. It never says whether images are returned inline, as URLs, or as file paths, whether results are paginated or capped, what permissions are needed, or what happens for an unrecognized tab value. The only behavioral hints are marketing-style claims ('genuine high-resolution 4K Retina'), plus a fixed account identifier that raises an unanswered question about scoping.
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 purpose is front-loaded in the opening clause, which is good. But it is one 60-word sentence padded with unverifiable adjectives ('genuine', 'production') and a raw email address, and the 22-module roster is dumped inline rather than summarized, making it harder to scan than it needs to be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and an undocumented parameter, the description is the only source of truth and it omits the two facts an agent most needs: the response shape (binary image vs. URL vs. metadata JSON) and how 'tab' behaves. It is complete only about what content exists, not about how to invoke or consume it.
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 0% and the single 'tab' parameter has no description, type enum, or default explanation. The module list in the prose plausibly enumerates the valid tab values, but the description never states that the tab parameter maps to those names, nor what the null default does. With coverage below 50%, the description must compensate explicitly and does not.
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+resource combination: 'Retrieve ... production screenshots and metadata for Chatty dashboard modules', which is unambiguous and clearly distinct from every sibling tool in the list (none of which deal with screenshots). It does not name or contrast against any sibling, but no sibling is plausibly confusable here, so 4 rather than 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?
There is no statement of when to call this tool, when not to, or what it substitutes for. The 22-item module list hints at scopes but never explains whether a caller should pass one tab, omit tab entirely, or that omitting it returns everything. The hardcoded account email also gives no guidance on how a different caller would target their own account.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get visitor CSAT scores and feedback comments.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, yet it discloses only that data is retrieved. Nothing about whether this is read-only, whether results are paginated or date-bounded, how CSAT scores are represented (average, individual ratings, distribution), or whether empty feedback is included.
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?
One short, front-loaded sentence with no filler and no wasted clauses. Its brevity is efficient rather than bloated; the issue is under-specification, not verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a data-retrieval tool with no annotations, no output schema, and an entirely undocumented parameter, the description should establish scope, return shape, and any filtering behavior. None of that is present, leaving the agent unable to predict what comes back or how much data to expect.
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 0% and the single required parameter (bot_id) is never mentioned in the description. The word 'visitor' hints that results are scoped to a bot's visitors but does not tie those results to the bot_id argument, so the description adds little meaning 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?
States a specific verb ('Get') and a specific resource pair ('visitor CSAT scores and feedback comments'), which is clearly separable from siblings like get_conversation_transcript or analyze_sentiment_trends. It stops short of stating scope (per-bot? per-conversation? aggregated?) or naming a sibling it is not, which keeps it out of 5 territory.
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 when-to-use guidance, no prerequisites, and no alternatives named despite many adjacent analytics tools in the sibling list (get_bot_performance_scorecard, analyze_sentiment_trends, analyze_chatbot). The agent must infer from the name alone whether to call this or a broader analytics tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch Help Center performance analytics: total views, CSAT helpfulness rating, top articles, and unanswered search content gaps.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden; it does imply a read operation and discloses the returned metric categories, which is useful. However, it says nothing about time-range scoping (notably absent from the schema), permissions, or whether metrics are per-article vs aggregate, leaving real gaps for a no-annotation tool.
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 that lists the returned metrics with zero filler; every clause adds 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 one-parameter read tool with no output schema, the description usefully enumerates the returned metrics. But the total absence of annotation coverage and the undocumented bot_id scoping leave it short of what an agent needs to call it 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 0%, so the single parameter bot_id is completely undocumented in both schema and description. The description should clarify that the analytics are scoped to one bot, but it never mentions bot_id or the scoping implication.
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 uses a specific verb ('Fetch') with a well-defined resource ('Help Center performance analytics') and enumerates the four data categories returned (views, CSAT, top articles, unanswered search gaps). It is clear enough to pick over siblings like get_feedback_and_csat, though it never explicitly names the boundary between them.
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 statement of when to use this tool, no prerequisites, and no reference to alternatives such as get_feedback_and_csat or discover_knowledge_gaps, which overlap in scope. Usage is only inferable from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch complete article details including full markdown/HTML content, category, and CSAT metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| article_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Fetch' plus a concrete return list (content, category, CSAT) correctly signals a read-only, single-record retrieval, which is useful. However, nothing is said about permission requirements, behavior when the article or bot_id is invalid, or payload size from full markdown/HTML.
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?
One sentence, front-loaded with the verb and resource, with the return payload appended. No filler or restated boilerplate.
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 usefully enumerates what comes back, which is a real contribution. But it leaves the two required identifiers unexplained and gives no signal about response size or failure modes for what is a bulk-content retrieval.
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 0% and both parameters (bot_id, article_id) are undocumented in the schema. The description only echoes 'article' implicitly and never mentions bot_id at all, so it fails to compensate for the coverage gap on a two-parameter tool.
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 ('Fetch') and resource ('article details') and enumerates the payload (full markdown/HTML content, category, CSAT metrics), which implicitly separates it from list_help_center_articles. It never names the sibling or says it is the single-article complement to the list tool, so differentiation is inferred rather than stated.
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 word 'complete' hints that this is the tool to reach for when the list view's summary is insufficient, but there is no explicit when-to-use guidance, no mention of the list/create/update/delete siblings, and no prerequisites. Usage must be inferred from the verb and resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get total characters indexed, knowledge source breakdown (URLs, text, files), and RAG health.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Get' implies a read-only operation and the description usefully discloses what data is returned (character counts, breakdown, RAG health), but it says nothing about permissions, cost, or latency.
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 efficient sentence that front-loads the primary returned metric (total characters indexed) and then the breakdown. 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?
With no output schema, the description does the work of listing return fields, which is helpful. However, with no annotations and an undocumented required parameter, an agent still lacks clarity on read-only semantics and parameter meaning.
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 single parameter bot_id is required but has 0% schema description coverage, and the description never explains it. Its meaning is fairly intuitive from the name, but the description adds no compensating detail.
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 'knowledge sync status', and enumerates the returned content (indexed character count, source breakdown by URL/text/file, RAG health). This is clearly distinct from list_knowledge_sources or test_rag_retrieval, though it doesn't explicitly name 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?
There is no guidance on when to use this tool versus related siblings like list_knowledge_sources, test_rag_retrieval, or purge_bot_knowledge. Usage is only implied by the name and returned fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the log of outgoing meeting-confirmation emails/push notifications sent by this bot.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It does add useful scope (only outgoing meeting-confirmation messages, not all mailbox traffic), but says nothing about ordering, pagination, retention window, or permissions required to read the log.
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 well-formed sentence with no filler, and the defining scope constraint is front-loaded. Its brevity is efficient, though at the cost of the missing details noted elsewhere.
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 annotations, no output schema, and 0% parameter coverage, the description should compensate more. It never indicates what a log entry contains, whether results are ordered, or how 'limit' behaves, leaving the agent to call a paginated listing tool blind.
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 0%: 'bot_id' and 'limit' have no documented meaning in the schema. The description only weakly implies that bot_id selects 'this bot'; 'limit' (default 50) is entirely unexplained, and the description gives no hint about its semantics or bounds.
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 a precisely scoped resource: the log of *outgoing meeting-confirmation* emails/push notifications sent by this bot. The scoping ('meeting-confirmation', 'outgoing', 'sent by this bot') makes it distinguishable from generic list/transcript tools. It does not name a sibling or say how it differs from list_meetings, 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?
There is no indication of when to use this versus list_meetings, get_conversation_transcript, or configure_notifications, nor any prerequisites or exclusions. The agent must infer usage entirely from the name and one-line purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current LiveKit voice agent configuration for a chatbot (models, visualizer, enabled status, provider keys status).
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It usefully discloses that the response includes models, visualizer, enabled status, and provider keys status, but it does not mention permissions, sensitivity of provider key status, or any rate-limit/auth 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?
A single front-loaded sentence with no waste. The parenthetical list of included fields is compact and useful.
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 read tool with no output schema and no annotations, the description is mostly sufficient: it identifies the target resource and summarizes returned fields. It still leaves bot_id semantics and any permission/sensitivity considerations unexplained, so it is not fully 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 is one required parameter, bot_id, and schema description coverage is 0%; the description never mentions bot_id or its expected format. The phrase 'for a chatbot' weakly implies the parameter identifies a bot, but it does not compensate for the missing parameter documentation.
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: get the current LiveKit voice agent configuration for a chatbot. The parenthetical enumerates what the config includes, so the agent can distinguish it from configure_voice_agent, though it does not explicitly name 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?
The description says what the tool retrieves but does not explain when to use it versus alternatives such as get_chatbot, configure_voice_agent, or get_voice_agent_embed_code. Usage is only implied by the word 'get'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate embed code and SDK snippets for embedding the LiveKit Voice Agent.
Frameworks: 'html_script', 'react', 'iframe', 'ios', 'android', 'flutter', 'react_native'.
Display modes: 'modal' (voice popup modal), 'drawer' (side slide-over panel).
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| display | No | modal | |
| framework | No | html_script |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It never states that this is a non-mutating code-generation call, what preconditions exist (e.g., configure_voice_agent must have been run), or what form the result takes — the framework/display listing is only parameter help, not 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?
Front-loaded with the core action in the first sentence, followed by two compact value lists that each earn their place given the empty schema. Minor waste in the fragmented line breaks but nothing extraneous.
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, no-annotation, no-output-schema tool, the description covers the value space of two optional parameters but omits the required bot_id, prerequisites, and the shape of the returned snippet. An agent could call it, but not with full confidence.
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 0% with no enums declared, so the description is the only source of valid values — it usefully enumerates all seven framework values and both display modes with parenthetical explanations. However, it says nothing about bot_id, the one required parameter, leaving its meaning to inference from the name.
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 ('Generate') and resource ('embed code and SDK snippets') scoped to the LiveKit Voice Agent, which implicitly distinguishes it from the sibling generate_embed_code for the chat widget. It does not explicitly name that sibling or state the distinction, so it falls 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?
Usage is implied by the resource ('embedding the LiveKit Voice Agent'), but there is no explicit when-to-use guidance, no mention of prerequisites (a configured voice agent), and no routing away from the similarly named generate_embed_code sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect WooCommerce integration status, synced products count, and sync freshness.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. 'Inspect' implies a read operation, but the description does not state required permissions, integration prerequisites, error behavior, or rate limits, leaving significant behavioral gaps for an unannotated tool.
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 front-loaded sentence with no wasted words. It states the core purpose and the key data fields 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?
For a simple one-parameter read tool, the description explains what status information is returned. However, it omits any explanation of the required bot_id parameter and provides no output-format context, which leaves a notable gap given the 0% schema coverage and absence of annotations.
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 0% and the only parameter, bot_id, is not mentioned in the description. The description adds no meaning about which bot identifier is required or what format it takes, so it fails to compensate for the undocumented 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 ('Inspect') and resource ('WooCommerce integration status'), and it clarifies the included data ('synced products count, and sync freshness'). It is distinguishable from sibling tools like configure_woocommerce and sync_woocommerce_products, though it does not explicitly reference those alternatives.
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 no explicit when-to-use guidance, no exclusions, and no named alternatives. An agent can infer it is a read-only status check, but there is no instruction on when to choose it over sync_woocommerce_products or configure_woocommerce.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause AI responses to allow a human support agent to take over the live chat.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| pause_ai | No | ||
| session_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that AI responses are paused, but does not mention permissions, reversibility (how to resume AI), side effects, or what the tool returns. For a state-mutating operation with three parameters, this is a significant gap.
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 single sentence is efficient, front-loaded with the core action, and contains no filler. It could optionally include a bit more context, but it is well-structured for a quick-purpose statement.
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 the tool's complexity (a state-changing operation with required IDs, no annotations, no output schema, and zero parameter documentation), the description is incomplete. An agent would not know how to resume AI, what permissions are needed, or what the call returns, making it under-specified for reliable invocation.
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 0%, and the description does not explain any of the three parameters. 'Pause AI' hints at the pause_ai flag, but there is no explanation of bot_id or session_id, nor of what happens when pause_ai is false. The description adds almost no meaning beyond the parameter names.
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 action: pause AI responses to enable a human takeover of a live chat. It clearly conveys the resource (live chat) and the mechanism (pausing AI), setting it apart from a simple message-sending tool. However, it does not explicitly contrast with siblings like send_agent_message, which also operate on live conversations.
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, no prerequisites, and no indication of when not to use it. The phrase 'allow a human support agent to take over' implies a context, but does not tell the agent when to choose this action over, say, sending a message or adding an internal note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active API keys (chatty_sk_...) for a bot with their usage stats and last-used dates.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that only active keys are listed and that usage stats and last-used dates are included, which is useful context. However, it omits permission requirements, pagination behavior, and whether inactive keys are excluded or accessible elsewhere.
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, front-loaded sentence with no redundant or filler content. It efficiently conveys the primary operation, scope, and return values.
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 list tool with no annotations and no output schema, the description covers the core purpose and return fields. It is still incomplete regarding permissions, pagination, and how the single required parameter should be sourced or formatted.
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 0%, so the description must compensate for the undocumented bot_id parameter. It only implies that the bot_id identifies 'a bot', without clarifying expected format, whether it accepts names or IDs, or where to obtain the value.
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 'active API keys' for a specific bot, including a key-format example and return details. It distinguishes itself semantically from sibling tools like create_api_key and revoke_api_key, though it does not explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives such as create_api_key or revoke_api_key. It merely describes what the tool returns, leaving the agent to infer the use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all proactive campaigns created for a bot.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and delivers almost none of it. It does not say whether results are paginated, whether 'all' means unbounded, what fields a campaign has, or what permissions the caller needs; only the read-only nature is implied by 'List'.
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 efficient sentence with the key scoping information ('for a bot') placed where it is read first. No filler, though the brevity borders on under-specification rather than deliberate tightness.
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?
No annotations, no output schema, and 0% parameter coverage mean the description is the only source of context, and it does not cover return shape, result size, pagination, or required-parameter behavior. For a list endpoint that could return an arbitrary number of records, that is a 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 0% for the single required parameter bot_id, whose meaning comes only indirectly from the phrase 'for a bot'. The description adds no format, source, or validation meaning beyond that implication.
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 all proactive campaigns') and scopes it to a bot, which cleanly separates it from create_campaign, update_campaign, delete_campaign, and get_campaign_analytics. It stops short of naming those siblings, so differentiation is implicit rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance and no alternatives. An agent must infer from the name alone whether to use this versus get_campaign_analytics when it wants campaign information, and no prerequisite or context is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every chatbot owned or accessible by the authenticated user's account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that results are limited to chatbots owned by or accessible to the authenticated account, which is useful scope information, but it does not mention pagination, ordering, or return format.
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 efficient sentence with the resource and scope front-loaded. There is no redundant or filler text.
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-parameter list tool with no output schema, the description adequately explains what is being listed and the ownership scope. However, it omits whether results are paginated or what the response contains, which an agent may need to know.
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 are no parameter semantics to explain. Baseline for a zero-parameter tool is appropriate, and the description adds nothing misleading.
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 chatbots. The scope phrase 'owned or accessible by the authenticated user's account' clarifies what is listed, though it does not explicitly distinguish this from fetching a single chatbot via get_chatbot.
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 guidance is given on when to use this versus get_chatbot or other chatbot-related siblings. The description does not state prerequisites, exclusions, or the alternative tool for retrieving details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private agent notes on a conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| session_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden; 'private agent notes' does disclose an important visibility trait (internal-only content), and 'List' implies a non-destructive read. It says nothing about pagination, ordering, empty-result behavior, or whether notes are scoped per bot, which are real gaps for an undocumented read tool.
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. It is efficiently written, though the terseness is part of the under-specification problem rather than a true strength.
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 annotations, no output schema, and two undocumented required parameters, the description leaves too much unknown: it does not describe the returned note shape (author, timestamp, body) or pagination. For a listing tool keyed on two opaque IDs, more context is needed.
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 0% for both required parameters, so the schema supplies only bare titles (bot_id, session_id). The description only hints that the tool operates 'on a conversation' (implying session_id) and says nothing about what bot_id scopes or whether notes are shared across bots.
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 notes on a conversation) and adds a meaningful qualifier: the notes are private/agent-facing, not customer-visible. It does not distinguish itself from the write sibling add_conversation_internal_note or from get_conversation_transcript, so an agent gets the gist but no explicit routing cue.
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 when-to-use guidance, no prerequisites, and no mention of the complementary tools (add_conversation_internal_note to create notes, get_conversation_transcript to read the conversation itself). Usage is only inferable from the name, and nothing tells the agent when not to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent visitor conversation sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| bot_id | Yes | ||
| status | No | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that results are 'recent' but does not explain ordering, pagination, permissions, bot scoping, or how status filtering affects results.
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 sentence, front-loaded with the verb and resource, with no filler or 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 tool with three parameters, no annotations, no output schema, and zero schema descriptions, one sentence is insufficient. An agent lacks guidance on required bot_id, status filtering, result count, and return shape.
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 0% and the description mentions none of the three parameters. Required bot_id is undocumented, and the meaning/default behavior of limit and status is absent; 'recent' only vaguely hints at result count.
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 'visitor conversation sessions' with recency scope. However, it does not differentiate from nearby list/get conversation tools such as list_conversation_notes or get_conversation_transcript.
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 when-to-use guidance, exclusions, or alternatives are given. The only implied usage is retrieving recent sessions, leaving the agent to infer when this is preferable to sibling conversation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Help Center articles with metrics (views, helpful votes), category details, and optional filters.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| search | No | ||
| status | No | ||
| category_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries full burden: it does confirm this is a read operation and names the metric fields returned, which is useful since there is no output schema. It omits pagination/result limits, what 'status' values are legal, and any bot-scoping or permission implications for bot_id.
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 well-formed sentence with the primary action front-loaded and zero filler. Nothing is redundant, though the terseness is also the source of the semantic gaps scored elsewhere.
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 four-parameter tool with 0% schema coverage, no annotations, and no output schema, the description is too thin — parameters are uncharacterized and there is no guidance on result size or pagination. Only the return-field preview partially fills the void left by the missing 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 description coverage is 0%, so all four parameters are undocumented in structured data. The description compensates only with the vague phrase "optional filters," giving no meaning for search (substring? fuzzy?), status (what values?), or category_id — and bot_id, the sole required parameter, is never mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource ("List all Help Center articles") and previews the returned content (views, helpful votes, category details). It reads clearly against the single-article sibling get_help_center_article, but never names that sibling or list_help_center_categories 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?
The only usage signal is the phrase "optional filters" — no statement of when to call this versus get_help_center_article, how the filters combine, or whether search/status/category_id are ANDed or exclusive. An agent must infer everything about selection conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Help Center categories for a chatbot, including article counts and icons.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden itself; 'List all' usefully implies an unpaginated read and it discloses that counts and icons are returned. It says nothing about permissions, ordering, or behavior with an invalid/empty bot_id.
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?
One sentence, front-loaded with the action and resource, with the return highlights appended. Nothing to trim and nothing buried.
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 one-parameter read tool with no output schema, the description covers the action, scope, and key return fields. Only minor gaps remain (pagination and ordering), which is acceptable at this 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 description coverage is 0% for the single required bot_id, so the description has to compensate. 'for a chatbot' loosely maps bot_id to the chatbot whose categories are listed, but it adds no format or sourcing detail beyond that implication.
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 all Help Center categories') scoped to a chatbot, and previews the payload ('article counts and icons'). This clearly separates it from article-level siblings like list_help_center_articles and get_help_center_article, though it doesn't name any alternative 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?
No when-to-use guidance, no prerequisites, and no routing to alternatives among the many help-center and listing tools. Usage is only implied by the phrase 'for a chatbot'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all indexed knowledge sources, character counts, and training statuses.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read-only operation, but it says nothing about required permissions, scoping to a bot, pagination, or whether untrained/failed sources are included — significant gaps for a tool with zero annotation coverage.
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 well-formed sentence with no filler, and the resource is front-loaded before the returned fields. Nothing needs trimming.
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 description usefully hints at the return content (character counts, training statuses) despite no output schema, but it leaves the sole required parameter and the bot-scoping behavior undocumented with no annotations to compensate. Adequate but with a clear 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?
There is one required parameter (bot_id) with 0% schema description coverage, and the description never mentions it, so the agent must infer that the listing is scoped to a bot. With 0 params the baseline would be 4, but here the single undocumented parameter is entirely unaddressed.
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 (indexed knowledge sources) and even names the fields returned (character counts, training statuses). It is clearly distinguishable from siblings like add_chatbot_knowledge or delete_knowledge_source, though it never explicitly contrasts with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, no prerequisites, and no pointer to alternatives such as get_knowledge_sync_status or discover_knowledge_gaps. Usage is only implied by the verb 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List captured visitor contact leads.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states that leads are listed. It does not disclose whether results are scoped to a bot, how pagination works, what permissions are needed, or what fields are 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?
The description is a single front-loaded sentence with no wasted words, so it is concise and easy to parse. However, its brevity reflects under-specification rather than efficient communication of the information an agent needs.
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 annotations, no output schema, and 0% schema description coverage, yet the description only states the basic purpose. An agent would still lack critical context about required bot scoping, result limits, and return behavior.
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 0%, so the description must compensate for the two undocumented parameters. It says nothing about bot_id, which is required, or limit, which defaults to 100, leaving both parameters semantically unexplained.
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 uses a specific verb and resource: 'List captured visitor contact leads.' It clearly identifies the resource as visitor contact leads, though it does not distinguish this operation from sibling tools such as export_leads or configure_lead_capture.
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 like export_leads, nor any mention of filtering, pagination, or prerequisites. The only implied usage is that the tool lists leads, which is already evident from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List meetings booked by visitors through the chatbot.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does not disclose whether results are paginated, sorted, date-filtered, or what permissions are required, and it does not describe the return shape for a listing 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?
A single efficient sentence with the resource front-loaded after the verb. No wasted words, though it is arguably too terse for a listing tool.
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?
No output schema, no annotations, and an undocumented required parameter leave significant gaps: the agent cannot know the return format, ordering, or whether pagination or filtering exists. The description does not compensate for this thin structured context.
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 0% for the single required parameter 'bot_id', and the description never explains that meetings are scoped to a specific bot or what a bot_id looks like. The description adds no meaning beyond the bare parameter name.
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 ('meetings booked by visitors through the chatbot'), which is clearly distinguishable from siblings like list_leads or list_conversations. No explicit sibling differentiation or scope constraints, but the purpose 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?
There is no guidance on when to use this tool versus list_conversations, list_leads, or lead-export tools. The agent must infer usage entirely from the one-line description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List event-webhook subscriptions configured for a bot.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It implies a read operation but says nothing about pagination, ordering, whether inactive/disabled subscriptions are included, return shape, or permission requirements for the calling bot.
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 wasted words. It is efficient, though it verges on under-specification rather than being an exemplary tight definition.
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 one-parameter read tool with no output schema and no annotations, the description is minimally adequate: an agent knows what it fetches and for which bot. It omits all scoping behavior (pagination, filtering, ordering) that an agent would want before relying on the result set.
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 one parameter with 0% schema description coverage. The phrase 'for a bot' implicitly maps bot_id to the owning bot, but the description adds no format, source, or lookup guidance beyond that bare association.
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 ('event-webhook subscriptions') scoped to a bot, which is enough to tell it apart from create_webhook_subscription and delete_webhook_subscription among the siblings. It stops short of any explicit sibling differentiation, but the verb+resource pairing 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?
No statement of when to use this versus create/delete webhook tools, no prerequisites, and no mention of what to do next after listing. Usage is only implied by the tool name and the 'List' verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invite, update, or remove team members for a chatbot, optionally setting custom tab permissions.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | agent | |
| Yes | |||
| action | Yes | ||
| bot_id | Yes | ||
| permissions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose whether removal immediately revokes access, whether changes are reversible, what permissions are needed to invoke it, or what the response contains. For a mutation tool with no annotation safety net, this is a significant gap.
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 single sentence is efficient and front-loaded with the core purpose. It wastes no words, though its brevity comes at the cost of necessary detail rather than being a model of structural completeness.
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 five parameters, an unconstrained `action` string, no output schema, and no annotations, the description is too thin. An agent cannot confidently map `action` values or understand side effects from this sentence alone.
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 0%, so the description must compensate. It only clarifies that `permissions` refers to custom tab permissions; it leaves `action` without any list of accepted values, `role` without valid roles beyond the default, and `email`/`bot_id` with no format guidance.
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 set of verbs (invite, update, remove) and a clear resource (team members) scoped to a chatbot. It is unambiguous about what the tool does, though there are no sibling team-management tools to differentiate from.
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 implies that the tool handles membership lifecycle changes but never specifies when to choose invite vs. update vs. remove, what role values are valid, or whether any permissions or plan restrictions are required. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a standalone live HTML preview of the customized Shadow-DOM widget.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| test_theme | No | light |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It does not disclose whether the preview is read-only, whether it persists anything, what permissions are needed, or what kind of side effects occur.
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 front-loaded sentence with no waste. It states the tool's core action and output format 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?
An output schema exists, so the description need not explain return values. However, with no annotations and 0% schema description coverage, the description is incomplete: it omits parameter meaning, usage conditions, and behavioral traits needed to invoke the tool 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 description coverage is 0%, and the description does not explain either parameter. It never mentions bot_id, test_theme, or the default value 'light', leaving an agent without semantic guidance for required and optional inputs.
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: 'Generate a standalone live HTML preview of the customized Shadow-DOM widget.' This clearly distinguishes it from broad styling or embed-related siblings, but it does not explicitly name the closest alternatives such as generate_embed_code or customize_widget_styling.
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 used to preview a customized widget, but it gives no explicit guidance on when to use it versus generate_embed_code, analyze_widget_design, or test_chatbot_reply. It also does not state prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purge knowledge sources for a bot (optionally filter by source_type: 'url', 'text', 'document').
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| source_type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. 'Purge' signals a destructive operation, but the description does not disclose irreversibility, permissions, default scope when source_type is omitted, or 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?
The description is a single front-loaded sentence with the verb and resource first and the optional filter immediately after. There is no wasted text.
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 annotations, no output schema, and a destructive operation, the description is too thin. It does not explain the consequences of purging, whether the default purges all sources, permissions required, or expected response.
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 0%, so the description should compensate. It usefully documents that source_type is optional and lists allowed values ('url', 'text', 'document'), but bot_id is only implied by 'for a bot' and the null/default behavior is not explained.
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: 'Purge knowledge sources for a bot.' It also clarifies the optional source_type filter with concrete values. It does not explicitly distinguish this bulk purge operation from the sibling delete_knowledge_source, so it falls 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 description implies usage by naming the operation and the optional filter, but it gives no explicit guidance on when to use this tool versus delete_knowledge_source or list_knowledge_sources. It also does not state when not to use it or warn that omitting source_type may purge all sources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke an API key immediately to deny further access.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| key_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that revocation is immediate and denies further access, but it does not state whether revocation is permanent or reversible, what permissions are required, or what happens on failure.
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 front-loaded sentence with no wasted words. However, for a destructive operation with no annotations and undocumented parameters, it is arguably too sparse to be appropriately sized.
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 the complete absence of annotations, schema descriptions, and output schema, the description is not complete enough for a destructive mutation tool. It omits irreversibility, required permissions, failure modes, and return behavior, which an agent needs before invoking it.
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 description coverage is 0%, and both required parameters, bot_id and key_id, have no descriptions in the schema. The description mentions only 'an API key' and does not explain which parameter identifies the bot versus the key, leaving parameter meaning undocumented.
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: revoke an API key, and adds the immediate effect of denying further access. It is clearly distinct from create_api_key and list_api_keys by action, but it does not explicitly differentiate itself from siblings or name alternatives.
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 sentence implies that the tool is used to cut off access, but it gives no explicit when-to-use guidance, prerequisites, or alternatives such as list_api_keys for inspecting keys first. There is no warning about when not to use this destructive action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a human agent message into an active visitor conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| message | Yes | ||
| session_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that the conversation must be active, which is useful, but it does not describe permissions, external side effects on the visitor, behavior if the session is inactive, rate limits, or what the tool returns.
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 front-loaded sentence with no filler and no redundancy. It is structurally efficient, though its brevity contributes to gaps covered in other dimensions.
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 mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is materially incomplete. It identifies the core action but omits parameter meaning, authorization needs, side effects, and error/edge-case behavior.
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 0%, so the description must compensate for all three required parameters. It only makes 'message' self-evident and hints at session context via 'conversation'; bot_id and session_id are left unexplained, including format or sourcing.
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: 'Send a human agent message', and scopes it to 'an active visitor conversation'. It is clear what the tool does, though it does not explicitly distinguish itself from siblings such as add_conversation_internal_note or human_agent_takeover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like add_conversation_internal_note or human_agent_takeover. The only implied precondition is that the conversation be active, but no exclusions, prerequisites, or decision criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index a Google Drive or OneDrive folder (provider='gdrive'|'onedrive') into the account's knowledge base. Requires the account already connected that provider from the dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| provider | Yes | ||
| max_files | No | ||
| folder_id_or_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses the provider-connection prerequisite, but says nothing about whether indexing is asynchronous and returns a job handle, whether a re-sync replaces or merges existing knowledge, what happens to sources already indexed, or what file types/limits apply. For a mutation-style ingestion tool with zero annotation coverage, that is a significant gap.
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, zero waste, and the core purpose is front-loaded ahead of the caveat. 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 and no annotations, the description should explain what a successful call returns (a sync job or immediate result?) and roughly how much/long the indexing runs. None of that is present, and two of four parameters are unaddressed, leaving the agent under-informed for a four-parameter ingestion operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does add genuinely new semantics for `provider` by spelling out the accepted values 'gdrive'|'onedrive' — the schema declares no enum — and implies `folder_id_or_url` refers to a folder. But `bot_id` and `max_files` (default 50) go entirely undocumented in both schema and description.
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?
Specific verb plus resource: 'Index a Google Drive or OneDrive folder ... into the account's knowledge base' tells an agent exactly what will happen and to which data. It is distinguishable from crawl_website_knowledge and upload_knowledge_document by the Drive/OneDrive resource, though they are not named, so the differentiation must be inferred.
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 supplies a real precondition ('Requires the account already connected that provider from the dashboard'), which is the main reason a call would fail. However it gives no guidance on when to prefer this over sibling ingestion tools (add_chatbot_knowledge, crawl_website_knowledge, upload_knowledge_document) and never points to get_knowledge_sync_status for tracking an ongoing sync.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a catalog sync of WooCommerce products into the chatbot's knowledge base.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the entire behavioral burden. It doesn't disclose whether the sync is asynchronous or returns a job/run handle, whether it replaces or merges existing product knowledge, whether it requires prior WooCommerce configuration, or what permissions/rate limits apply. Only the destination ('knowledge base') is implied.
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?
One sentence, front-loaded with the action and ending with the target location; no filler. It's appropriately sized for what it says, though the terseness leaves real gaps rather than wasting 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?
This is a mutation/sync tool with no annotations, no output schema, and an unexplained required parameter. The description should at minimum clarify the bot_id role, whether the operation is async, and how sync status can be checked (e.g., get_knowledge_sync_status). None of that is present.
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 0% for the single parameter bot_id, and the description never mentions it. An agent gets no explanation of what bot_id identifies (which chatbot receives the synced catalog) or its format, so the description fails to compensate for the empty 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 ('Trigger a catalog sync') and a specific resource ('WooCommerce products into the chatbot's knowledge base'), which is far more informative than a bare name restatement. It doesn't explicitly contrast with configuration siblings (configure_woocommerce, get_woocommerce_store_status), 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 description only implies when to use it – whenever a catalog sync is desired. It never says when not to use it, what prerequisites exist (e.g., store must be configured via configure_woocommerce first), or how it relates to alternatives like add_chatbot_knowledge or sync_cloud_storage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate a visitor question to test the bot's RAG retrieval, citations, and reply matching.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does not say whether the simulated message is persisted as a real conversation, whether it affects analytics, or whether it consumes quota. 'Simulate' hints at non-destructive behavior but never confirms it.
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 efficient sentence with the capability front-loaded and no filler. Slightly under-specified rather than over-long, but structure itself is good.
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 annotations, no output schema, and zero parameter documentation, the agent cannot tell what the call returns (the matched reply? citations? retrieval scores?) or what side effects it has. For a testing tool whose whole value is its output, that 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 0% for both required params. The description only loosely suggests what 'message' is ('a visitor question') and says nothing about bot_id format or whether message supports markup or variables, so it does not compensate for the undocumented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (simulate a visitor question) and names concrete targets: RAG retrieval, citations, and reply matching of a bot. It is clearly distinct from generic chat tools, though it never distinguishes itself from the close sibling test_rag_retrieval.
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 statement of when to use this instead of the near-identical test_rag_retrieval sibling, and no prerequisites (e.g., must knowledge be crawled/indexed first). Usage is only implied by the word 'simulate'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate a test query against the bot's vector index and inspect retrieved chunks.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No | ||
| bot_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'Simulate' weakly implies a non-mutating dry run, but the definition never confirms that it does not alter the index or consume quota, nor does it describe the shape or ordering of the returned chunks, which is the stated point of the call.
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?
One compact sentence with the action front-loaded and zero filler. It is efficient, though the available space is arguably underused given the undocumented parameters.
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 three-parameter tool with zero schema descriptions, no annotations, and no output schema, the description should explain the parameters and what the returned chunks look like. Neither is covered, leaving an agent able to guess the intent but not to call it precisely.
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 0%, so the description must compensate and it does not — it never mentions query, bot_id, or top_k. The top_k parameter in particular has a non-obvious default of 4 that an agent would want explained (e.g., max value, effect on latency).
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 action (simulate a test query against the vector index) and the resource inspected (retrieved chunks), so the purpose is unambiguous. It does not explicitly distinguish itself from the nearby test_chatbot_reply, which also tests bot behavior, so sibling differentiation 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?
There is no guidance on when to use this versus test_chatbot_reply, discover_knowledge_gaps, or get_knowledge_sync_status — all plausible alternatives in a RAG-debugging workflow. The word 'Simulate' hints at a diagnostic use case, but no conditions, prerequisites, or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing campaign (only passed fields are modified).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| bot_id | Yes | ||
| end_date | No | ||
| is_active | No | ||
| start_date | No | ||
| campaign_id | Yes | ||
| trigger_type | No | ||
| url_patterns | No | ||
| campaign_type | No | ||
| trigger_value | No | ||
| target_devices | No | ||
| message_content | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does add one important trait beyond the schema: that only passed fields are modified (partial-update semantics), which helps distinguish PATCH-like behavior. However, it omits permissions, validation rules, whether explicit null clears a field, and the consequences of changing campaign state.
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 waste. The partial-update caveat is placed immediately after the core action, making the key information easy to find.
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 12-parameter mutation tool with no annotations, no output schema, and no parameter descriptions, a one-sentence description is far too thin. It covers the basic action and partial-update behavior but leaves critical gaps around parameter meanings, validation, and permissions.
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 0%, so the description should compensate, but it provides no meaning for any of the 12 parameters. The clause 'only passed fields are modified' gives generic semantics for optional parameters but says nothing about name, dates, trigger_type, url_patterns, message_content, or the required bot_id/campaign_id identifiers.
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 ('Update an existing campaign'), which clearly sets it apart from create_campaign, delete_campaign, and list_campaigns by action type. It does not explicitly name those siblings, but the operation 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?
There is no explicit guidance on when to use this tool versus create_campaign, delete_campaign, or list_campaigns beyond the implied context of modifying an existing campaign. No prerequisites, permissions, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update settings for an existing chatbot (only passed fields are modified).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| bot_id | Yes | ||
| strict_mode | No | ||
| widget_style | No | ||
| primary_color | No | ||
| selected_model | No | ||
| welcome_message | No | ||
| response_language | No | ||
| system_instructions | No | ||
| lead_capture_enabled | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full burden and does contribute one genuinely useful trait: "only passed fields are modified" discloses PATCH-like semantics, so unset nullable fields are preserved. It says nothing about permissions, whether the updated bot is returned, uniqueness constraints on name, or whether changes are reversible — a substantial gap for a mutation tool with no annotation coverage.
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 scoping constraint is placed immediately after the purpose. Nothing redundant to remove.
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?
A 10-parameter mutation tool with 0% schema coverage, no annotations and no output schema is served by only one sentence. An agent cannot tell which fields matter, what valid values look like, or what comes back after the call.
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 0% across 10 parameters — only bare titles and nullable defaults. The description adds no meaning for any of them (no format for primary_color, no allowed values for selected_model or response_language, no explanation of strict_mode or widget_style), and never mentions that bot_id is required.
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 ("Update settings for an existing chatbot") so an agent knows exactly what operation is performed. However, it does no sibling differentiation despite overlapping siblings like update_chatbot_instructions and update_conversation_flow, and `system_instructions` being a parameter here makes that ambiguity real.
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 guidance on when to use this tool versus alternatives such as update_chatbot_instructions or clone_chatbot, and no prerequisites stated. The only usage-adjacent hint is the partial-update parenthetical, which is behavioral rather than a routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the AI persona, guidelines, rules, and system prompt for a chatbot.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| system_instructions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It states that instructions are updated but does not disclose whether the update replaces existing instructions, what permissions are required, whether the change is reversible, or what the response contains.
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 front-loaded sentence with no wasted words. It is appropriately sized for a simple two-parameter mutation tool, though its brevity contributes to gaps elsewhere.
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 mutation tool with no annotations, no output schema, and 0% schema parameter description coverage, the definition is not complete enough. An agent still lacks guidance on bot_id semantics, replacement behavior, permissions, and expected results.
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 0%, and the description does not explain the bot_id parameter at all. It loosely maps to system_instructions by mentioning 'system prompt,' but does not clarify whether the supplied text replaces or appends to existing instructions, nor any format or length 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 uses a specific verb (Update) and resource (chatbot instructions) and clarifies the covered fields: persona, guidelines, rules, and system prompt. It does not differentiate this from siblings such as update_chatbot or configure_guardrails, which could plausibly overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The name implies setting instructions, but there is no routing help among the many sibling configuration tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save and publish a visual conversation flow graph (nodes, triggers, messages) for a bot.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Chatty automation | |
| bot_id | Yes | ||
| enable | No | ||
| flow_data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the operation publishes a flow, which implies a live mutation, but does not explain permissions, whether the flow is replaced or merged, what 'enable' does, or other side effects.
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 efficient sentence with the action and resource front-loaded. Every phrase contributes to identifying what the tool does.
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 mutation tool with no annotations, no output schema, 4 parameters, and a nested flow_data object, the description is too thin. It omits prerequisites, side effects, parameter details, and return behavior, leaving meaningful gaps 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?
Schema description coverage is 0% across 4 parameters, so the description must compensate. It adds limited meaning by indicating flow_data contains nodes, triggers, and messages, but it never mentions the name or enable parameters and does not explain the required bot_id or nested flow_data structure.
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: 'Save and publish a visual conversation flow graph' for a bot. The resource is precise enough to distinguish it from get_conversation_flow (read) and update_chatbot (broader bot 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?
The description implies the tool is used when saving or publishing a flow, but it gives no explicit when-to-use guidance, exclusions, prerequisites, or comparison to siblings such as get_conversation_flow or update_chatbot.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a Help Center article, synchronizing changes to the bot's RAG vector memory.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | ||
| tags | No | ||
| title | No | ||
| bot_id | Yes | ||
| status | No | ||
| content | No | ||
| subtitle | No | ||
| article_id | Yes | ||
| visibility | No | ||
| category_id | No | ||
| is_promoted | No | ||
| order_index | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose one genuinely useful side effect: the RAG vector memory is re-synced. It does not say whether partial updates are supported (all 10 fields are optional natively), whether omitting a field leaves it unchanged or clears it, whether permissions are required, or whether the RAG sync is immediate or asynchronous.
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 the key side effect attached; nothing is wasted. Its brevity is only a problem because more needed to be said, which is captured elsewhere.
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 12-parameter mutation with no annotations, no output schema, and zero schema descriptions, the description is far too thin. An agent would not know update semantics, permission prerequisites, or the effect on the published article versus its RAG index.
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 0% across 12 parameters, so the description must compensate, and it says nothing about any parameter. No meaning is given for article_id/bot_id pairing, the visibility or status value spaces, or which fields are patchable.
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 Help Center article) and adds a distinguishing trait: changes propagate to the bot's RAG vector memory. It is clearly separable from create_help_center_article / delete_help_center_article siblings, though it does not say what an 'update' can touch.
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 indication of when to use this versus create_help_center_article, update_help_center_category, or the knowledge-sync tools. The only implied guidance is that the article must already exist, which the agent must infer from the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Help Center category.
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | ||
| name | No | ||
| slug | No | ||
| bot_id | Yes | ||
| category_id | Yes | ||
| description | No | ||
| order_index | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It never says whether this is a partial or full update, what happens to fields omitted (or passed as null), whether the change is reversible, or what permissions/scope are required for the mutation.
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 waste, but it is under-specified rather than concise — brevity comes at the cost of all operational detail an agent would need.
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 7-parameter unannotated mutation tool with no output schema and no documented parameters, one sentence is far from sufficient. Nothing tells the agent how to invoke it correctly or what it returns.
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?
Seven parameters with 0% schema description coverage and the description mentions none of them. The agent gets no explanation of name, slug, icon, description, order_index, or the required bot_id/category_id beyond their bare titles.
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 (Help Center category), and 'an existing' clarifies it modifies rather than creates. It does not distinguish itself from siblings like update_help_center_article, create_help_center_category, or delete_help_center_category beyond the resource noun.
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 when-to-use guidance, no prerequisites, no mention of when to prefer create/delete/update-article siblings. The word 'existing' hints that the category must already exist, but nothing else is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index a PDF, DOCX, XLSX, PPTX, image, or text file (base64-encoded, max 20MB) as a knowledge source.
| Name | Required | Description | Default |
|---|---|---|---|
| bot_id | Yes | ||
| file_name | Yes | ||
| mime_type | No | ||
| file_base64 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does disclose two useful traits beyond the schema: the payload must be base64-encoded and is capped at 20MB. It is silent on indexing latency (is it async?), whether re-uploading the same file duplicates or replaces a source, and any permission 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?
One front-loaded sentence with no filler; the format list, encoding requirement, and size cap each earn their 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 mutation tool with no annotations, no output schema, and zero schema parameter documentation, the description is under-specified. An agent still cannot infer what bot_id should reference, whether mime_type is required for correct parsing, or what happens on success (indexing job vs immediate availability).
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 0% and all four parameters are undocumented in the schema. The description clarifies only file_base64 (base64 encoding, formats, size limit); it says nothing about bot_id, file_name, or mime_type, leaving half the surface unexplained.
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 ('Index') and resource ('file ... as a knowledge source') and enumerates supported formats (PDF, DOCX, XLSX, PPTX, image, text), which lets an agent recognize the operation. It does not distinguish itself from siblings like add_chatbot_knowledge, crawl_website_knowledge, or sync_cloud_storage, all of which also add knowledge.
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 statement of when to use this tool versus the sibling ingestion paths (add_chatbot_knowledge, crawl_website_knowledge, sync_cloud_storage). Usage is only implied by the file-format list; no exclusions or prerequisites are given.
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.
add_chatbot_knowledgeadd_conversation_internal_noteanalyze_chatbotanalyze_sentiment_trendsanalyze_widget_designclone_chatbotconfigure_byokconfigure_calendar_integrationconfigure_domain_allowlistconfigure_guardrailsconfigure_lead_captureconfigure_notificationsconfigure_slack_escalationconfigure_voice_agentconfigure_whatsapp_integrationconfigure_woocommercecrawl_website_knowledgecreate_api_keycreate_campaigncreate_chatbotcreate_help_center_articlecreate_help_center_categorycreate_webhook_subscriptioncustomize_widget_stylingdelete_campaigndelete_chatbotdelete_help_center_articledelete_help_center_categorydelete_knowledge_sourcedelete_webhook_subscriptiondiscover_knowledge_gapsexport_leadsexport_visitor_datagenerate_claimable_demo_botgenerate_embed_codeget_account_billingget_audit_logsget_bot_performance_scorecardget_campaign_analyticsget_chatbotget_chatbot_instructionsget_conversation_flowget_conversation_transcriptget_customer_identity_guideget_dashboard_screenshotsget_feedback_and_csatget_help_center_analyticsget_help_center_articleget_knowledge_sync_statusget_mailbox_logsget_voice_agent_configget_voice_agent_embed_codeget_woocommerce_store_statushuman_agent_takeoverlist_api_keyslist_campaignslist_chatbotslist_conversation_noteslist_conversationslist_help_center_articleslist_help_center_categorieslist_knowledge_sourceslist_leadslist_meetingslist_webhook_subscriptionsmanage_team_memberspreview_widget_htmlpurge_bot_knowledgerevoke_api_keysend_agent_messagesync_cloud_storagesync_woocommerce_productstest_chatbot_replytest_rag_retrievalupdate_campaignupdate_chatbotupdate_chatbot_instructionsupdate_conversation_flowupdate_help_center_articleupdate_help_center_categoryupload_knowledge_document
Add one secure layer between your agents and this server.