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

With no annotations, the description carries full burden. It states it returns code examples and API references, which is sufficiently transparent for a read-only documentation tool, though it could elaborate on return format or limitations.

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?

Well-structured with sections and bullet points, front-loaded with purpose. Slight redundancy in listing features twice, but overall concise and easy to scan.

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 documentation retrieval tool with 2 enum parameters and no output schema, the description provides complete context on usage, features, and expected output, enabling correct tool selection.

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 explicitly detail each parameter. It implicitly refers to language and feature, but the enum values are mostly self-explanatory; missing explanations for less obvious ones like 'messages-drafts_v1'.

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 it retrieves Chat SDK documentation for building chat/messaging applications, lists example features, and distinguishes from siblings like get_sdk_documentation and how_to by specifying scope and 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?

Explicit 'When to use' and 'Do NOT use for' sections provide clear guidance on appropriate contexts and alternatives, naming get_sdk_documentation for non-chat and how_to for conceptual guides.

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

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

No annotations provided. Description does not disclose behavioral details beyond stating it returns content. Lacks info on read-only nature, authentication, or response 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?

Well-structured with sections, concise, no superfluous information. Every sentence is earned.

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?

Complete enough for a simple 1-parameter tool. Could mention response format, but the examples and scope are sufficient.

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 has 0% coverage, but description provides concrete enum examples in 'When to use' section, adding practical value beyond the schema's enum list.

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 it retrieves general migration guides for cross-cutting PubNub platform changes, specifying verb+resource. Distinguishes from sibling tools get_sdk_migration_guide and get_sdk_documentation.

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 lists when to use and when NOT to use, with concrete examples and alternative tools named (e.g., 'use get_sdk_migration_guide').

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

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

No annotations provided, so the description carries full burden. It clearly states it is a read operation fetching history, supports pagination with timetokens, and returns JSON. It could mention rate limits or authentication needs, but is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two clear sentences: one for purpose and one for usage details. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description notes the return format (JSON with content and metadata) and pagination. Parameters are well-described in schema. It could mention edge cases like empty channels but is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description briefly mentions providing channel names and pagination parameters but does not add significant meaning beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches historical messages from PubNub channels, distinguishing it from sibling tools like send_pubnub_message and subscribe_and_receive_pubnub_messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'call this tool whenever you need to access past message history,' which provides general guidance but does not explicitly state when not to use it or compare with alternatives.

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

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

No annotations are provided, so the description carries full burden. It mentions real-time data retrieval and JSON output, but lacks details on side effects, safety, rate limits, or authentication nuances. For a read operation, minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: purpose, usage guidance, output and requirements. Each sentence is essential and front-loaded. No wasted words, clear structure.

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 mentions JSON output but omits details on error handling, empty results, or rate limits. Given no output schema, it provides adequate but not comprehensive context for a tool with 5 parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds value by explaining the functional roles of parameters (channels/channelGroups for HereNow, uuid for WhereNow) and highlighting key requirements. This goes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves real-time presence information and distinguishes HereNow from WhereNow based on parameters. It uses specific verb 'retrieves' and resource 'presence information'. However, it does not explicitly differentiate from sibling tools, but the sibling set is diverse, making this tool unique.

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 guidance on when to use channels/channelGroups versus uuid for HereNow/WhereNow. It implies usage context but does not specify when not to use the tool or mention alternatives like other tools for similar tasks.

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

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

With no annotations provided, the description carries the full burden. It states the output includes 'code examples, API references, and implementation guides,' which implies a read-only, side-effect-free operation. However, it does not explicitly declare read-only safety or mention any restrictions, but for a documentation tool this is adequate.

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 well-structured with headings and bullet points, front-loading the purpose and providing all key information in a concise manner without unnecessary 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?

Given no output schema, the description adequately explains the return type (code examples, API references, implementation guides) and usage context. It could mention pagination or size limits, but for a documentation tool this is sufficient.

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 refers to 'specified language/feature combination' without explaining what the enum values mean or adding any parameter-specific details beyond the schema field names. This is a significant 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 clearly states 'Retrieve Core SDK documentation for low-level real-time features' with a specific verb and resource. It distinguishes from siblings by explicitly naming get_chat_sdk_documentation for chat apps and how_to for conceptual guides.

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 explicit 'When to use' and 'Do NOT use for' sections, with alternative tool names for each exclusion case, offering clear guidance on when to invoke this tool versus others.

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

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

No annotations are provided, so the description carries the burden. It states the tool returns 'migration guide content for the specified language and target version', which is a basic behavioral trait. It does not disclose any additional traits like idempotency, rate limits, or potential errors. The clarity is adequate but lacks depth for a fully transparent definition.

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 well-structured with clear sections and bullet points, front-loading the core purpose. Minor verbosity from markdown formatting (bold, line breaks) but overall efficient. Every sentence earns its place, though the 'When to use' and 'Do NOT use for' sections could be slightly condensed.

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 low complexity (two enum parameters, read-only behavior), the description sufficiently covers purpose, usage guidelines, and sibling differentiation. It lacks an output schema but explicitly states what is returned ('migration guide content'). This is adequate for the tool's simplicity.

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 missing parameter explanations. The description merely references 'specified language and target version' without adding details beyond the enum names (e.g., valid versions 7,8,10,13). It does not explain what each version maps to or any additional constraints. The enum values are self-explanatory, but the description adds minimal 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 uses the specific verb 'Retrieve' and clearly identifies the resource as 'SDK migration guides for upgrading between PubNub SDK versions'. It explicitly distinguishes from sibling tools like 'get_sdk_documentation' and 'get_chat_sdk_documentation' by naming them in the 'Do NOT use for' section.

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 includes explicit 'When to use' and 'Do NOT use for' sections, listing concrete scenarios (e.g., upgrading major versions, need step-by-step instructions) and specific sibling tool alternatives (e.g., 'get_sdk_documentation' for general docs). This provides clear guidance on when to invoke this tool vs. others.

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

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

No annotations are provided, so the description must cover behavioral traits. It does not mention rate limits, authentication needs, destructive potential, or response structure. Listing parameters and metrics is helpful but insufficient for behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with headings and separates parameter info from metric categories, but it is lengthy due to the exhaustive list of 75+ metrics. This could be trimmed or referenced externally to improve conciseness without losing clarity.

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 complexity (5 parameters, many enum values, no output schema or annotations), the description lacks return format, error handling, rate limits, and prerequisites. It explains parameters and metrics but leaves the overall usage context incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by summarizing parameter types and listing available metric categories, but does not provide deeper semantics beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Fetches usage metrics from the PubNub Admin API for an account, app, or keyset.' It specifies the verb (fetches), resource (usage metrics), and scope (account/app/keyset), distinguishing it from sibling tools like get_pubnub_messages or manage_apps which cover different 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?

The description explains what the tool does but offers no guidance on when to use it versus alternatives, nor any exclusions. It implicitly suggests usage for retrieving metrics, but lacks explicit context or comparisons to siblings like get_pubnub_presence.

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

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

No annotations are present, but the description does not disclose whether the tool is read-only, what the output looks like, or any side effects. For a simple retrieval tool, this is acceptable but not fully transparent.

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?

Description is well-structured with clear sections and no unnecessary words. It earns its place by providing actionable usage guidance.

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 tool is simple, the description omits what the return value is (e.g., text, markdown). With no output schema, this is a notable gap for an agent to understand the result.

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 adds no explanation for the 'slug' parameter beyond what the enum provides. The agent must infer that slug identifies a guide without explicit 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?

Description clearly states the tool retrieves conceptual guides for specific use cases and integrations. It distinguishes from siblings by naming alternatives in the 'Do NOT use' section.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit 'When to use' and 'Do NOT use for' sections with concrete sibling tool names, offering clear guidance on when to select alternatives.

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

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

With no annotations provided, the description fully covers behavioral traits: read-only operation, period restrictions, UTC timestamps, inability to sum top-N counts across periods, account plan requirements, and filtering nuances. This exceeds disclosure expectations.

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 well-structured with a clear opening, bullet points, and a numbered guide. It is slightly verbose for the amount of detail, but every sentence adds value. The front-loading of core purpose is effective.

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 11 parameters, no output schema, and no annotations, the description covers all critical aspects: entity scoping, endpoint selection, period constraints, parameter relationships, error handling (403), and operational caveats. It is fully sufficient for correct tool 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?

Although schema coverage is 100%, the description adds substantial context: entity scoping rules, endpoint routing by metric type, period applicability matrix, category requirement for top metrics, filter vs filters distinction, and default behaviors. This significantly enriches the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Queries PubNub Insights — read-only aggregated analytics scoped to an account, app, or keyset.' This specifies the verb (query), resource (PubNub Insights), and distinguishes it from sibling tools like get_usage_metrics.

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 'TOOL SELECTION GUIDE' provides detailed when-to-use instructions for metrics, periods, and parameters. However, it does not explicitly compare this tool to alternative sibling tools for similar queries, leaving some ambiguity for AI agent selection.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It only mentions the high-level CRUD operations without detailing side effects (e.g., data mutation, authentication requirements, rate limits, or pagination behavior). This is a significant gap for a mutation 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 three concise sentences, front-loaded with the purpose and immediately clarifying what objects and operations are supported. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (7 parameters, nested objects, no output schema), the description covers the core purpose but lacks details on error handling, return values, pagination, or filtering options. The schema provides some details, but the description could better integrate guidance for complex operations like membership management.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds little beyond what the schema already provides (e.g., 'user profiles' vs. schema's 'user metadata'). It does not provide new semantic guidance for parameters like 'id' or 'data' that would help the agent construct correct 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 clearly states it manages PubNub App Context for users, channels, and memberships, listing specific CRUD operations (get, set, remove, getAll). This distinguishes it from sibling tools like manage_apps or manage_keysets, which deal with different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this tool to manage user profiles, channel metadata, and membership relationships,' which gives clear context for when to use it. However, it does not mention when not to use it or suggest alternative tools for related but different tasks.

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

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

No annotations are provided, so the description carries the burden. It discloses that create and update are mutating operations, and list is read-only. It also mentions required fields per operation. However, it does not cover side effects, authentication needs, 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 concise with two sentences and bullet points for each operation. It is front-loaded and efficient, though the operation enum description in the schema is partially 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?

Given no output schema and no annotations, the description covers all operations and required fields adequately. It provides enough context for an agent to use the tool 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 100%, baseline 3. The description adds meaning by explicitly stating required fields per operation (e.g., data.name for create, data.id and data.name for update) and clarifying that data is not required for list, which goes beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it manages PubNub apps with three operations (list, create, update), using specific verbs and resource. It distinguishes from sibling tools like manage_keysets and manage_app_context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for each operation, specifying required fields for create and update. However, it does not explicitly state when not to use this tool or suggest alternatives among siblings.

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

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

No annotations are provided, so the description carries full burden. It discloses many behavioral traits: 2-step create workflow, cascading deletes, auto-injection of defaults, naming resolution, pre-flighting limits, ingestion delay, and the critical rule that QUERY decision input field names must match source query aliases. It also warns against deletion without confirmation.

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 very long and verbose, but it is well-structured with bold headers and sections. It could be more concise; some details (e.g., lengthy parameter descriptions for `data`) are repeated in the schema, and the TOOL SELECTION GUIDE could be shorter. Adequate but not optimally concise.

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 (18 parameters, nested objects, no output schema), the description is exceptionally complete. It covers all operations, constraints, edge cases, and usage guidance. There are no missing pieces relative to the tool's scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds significant contextual meaning beyond the schema, such as explaining the 2-step Decision create workflow, the critical naming rules for input fields, default action choices, and limit enforcement. It enriches the agent's understanding of how parameters interact.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Manages PubNub Illuminate resources' and lists all 16 supported operations across 5 resource types. It distinguishes itself from sibling tools which cover different PubNub services (chat, keysets, messages, etc.), making it unambiguous when to use this tool.

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 includes a 'TOOL SELECTION GUIDE' that provides best practices (intent-first, preview-first, start simple). However, it does not explicitly compare to sibling tools or state when to avoid using this tool. The implicit distinction from sibling tools is clear, but no exclusions are given.

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

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

No annotations are provided, so the description carries the full burden. It discloses that create sets default values for certain features, but it lacks information on authorization, rate limits, or whether update is partial or full replacement. Some behavioral traits are mentioned but gaps remain.

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 uses bullet points and is well-structured. It front-loads the overall purpose and then details each operation. It is relatively concise, though could be slightly more terse without losing meaning.

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 complex tool with 4 operations and no output schema, the description covers key aspects like required fields, defaults, and operation-specific instructions. It does not mention return values or error handling, which would be beneficial, but given the complexity, the description is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by summarizing parameter usage per operation (e.g., 'for create: {name, appId?, type, config}') and explaining the structure of config. This helps the agent understand the complex nested parameters beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool manages PubNub keysets with four distinct operations: get, list, create, update. It uses specific verbs and resource (keysets), distinguishing it from sibling tools like manage_apps or manage_app_context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for each operation (e.g., 'get' requires keyset ID, 'create' requires name and type and config). It includes guidance like asking for missing parameters. However, it does not explicitly compare to alternatives or state when not to use this tool.

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

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

With no annotations, the description carries full burden. It reveals that plain strings are auto-wrapped in a 'text' field, a useful detail. But it lacks disclosure of side effects (e.g., message delivery guarantees), error conditions, rate limits, or idempotency.

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 concise sentences: first states purpose and types, second adds key requirement and behavior nuance. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Core behavior is covered: sending messages with key requirements and type differentiation. Missing details on response format or error handling, but given no output schema, the description is mostly adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description adds value by explaining auto-wrapping of plain strings for the message parameter, and notes keys requirement beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool sends messages or signals to PubNub channels in real-time, and distinguishes between regular messages and lightweight signals. This differentiates it from sibling tools like get_pubnub_messages (retrieval) and subscribe_and_receive_pubnub_messages (receiving).

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 mentions the requirement for publish and subscribe keys and hints at obtaining them via manage_keysets tool. However, it does not specify when to use signals vs messages, nor does it exclude alternative tools for similar tasks.

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

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

Without annotations, the description discloses the subscription behavior and defaults for messageCount and timeout. However, it does not explain blocking behavior, how messages are returned, or the unsubscription process.

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 three sentences with no fluff. It front-loads the main purpose and adds essential details 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?

With no output schema, the description does not explain the return format, which is a minor gap. However, for a real-time subscription tool, the return is somewhat implied. It covers all parameters and gives usage hints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by specifying default values for messageCount and timeout, max timeout, and the source for keys (manage_keysets tool), going beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Subscribe to a PubNub channel and receive messages in real-time', providing a specific verb and resource. It distinguishes from sibling tools like get_pubnub_messages and send_pubnub_message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions the prerequisite of publish and subscribe keys, which helps in usage context. However, it lacks explicit guidance on when to use this tool versus alternatives like get_pubnub_messages.

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

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

No annotations are provided, so the description carries full burden. It implies a read-only operation (retrieving a guide) but does not explicitly state behavioral traits such as being non-destructive or requiring authentication. The name mismatch adds ambiguity.

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 well-structured with a clear first sentence and a numbered list of topics. However, the list is lengthy (13 items) and could be more concise. The front-loading is effective.

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 parameters or output schema, the description sufficiently explains what the tool returns—a comprehensive best practices guide. The list of topics provides adequate completeness for an agent to decide when to use 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 tool has no parameters, and the input schema is fully covered (100%). With zero parameters, the description need not explain them, and it provides sufficient context for the tool's function.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a PubNub best practices guide with a detailed list of topics. However, the tool name 'write_pubnub_app' contradicts the retrieval action, causing potential confusion. Despite the name, the purpose is well-defined.

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 mentions calling this tool when building PubNub applications for robust, scalable, and secure implementations. This provides usage context but lacks explicit guidance on when not to use it or how it differs from sibling tools like get_sdk_documentation.

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