supovia

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond this by disclosing the 50-record cap and the exact fields excluded (message body, preview, message id, etc.), giving the agent a precise, honest behavioral contract. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core purpose and scope, followed immediately by exclusions. 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?

Given the tool has an output schema (per context signals), the description does not need to explain return values. It covers purpose, limit, safe fields, and exclusions for a simple one-parameter read tool, leaving nothing essential 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 coverage is 100% for the only parameter (conversationId), with a basic description 'Conversation id'. The tool description adds no extra parameter semantics, so the baseline of 3 applies.

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

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

Description clearly states a specific verb ('summarize'), resource ('one organization-owned Supovia conversation'), and scope ('safe status fields and sender-category counts'). It also explicitly lists what is NOT returned, distinguishing it from more detailed conversation tools like open_customer_inbox_conversation or get_document.

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 context (safe summary from at most 50 recent records) and implicitly routes away from use cases needing sensitive fields by listing exclusions. It doesn't name alternative tools explicitly, but the exclusion list effectively tells an agent 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?

Annotations indicate readOnlyHint, idempotentHint, and non-destructive nature. The description goes beyond by specifying the character cap (20000), the contentFormat field's semantics, and the excluded data (organization ids, translator ids, deprecated slugs, embeddings, arbitrary metadata). It also reveals the consistent 'not found' result for other organizations, which is critical behavioral nuance not captured in annotations.

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

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

The description is moderately long but each sentence carries distinct information: what is fetched, the cap, the contentFormat, the cross-org behavior, and what is never returned. It is front-loaded with the core purpose and avoids redundancy. No fluff, though it could be slightly tighter by merging the first two sentences.

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 an output schema present, the description need not detail every return field, but it does cover the key aspects (article text cap, contentFormat) and explicitly lists excluded data. It also addresses a likely edge case (documents owned by other organizations). This is sufficient for an agent to correctly invoke the tool and interpret results. Minor gap: the locale default (en) is only in the schema, not the description.

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% – each parameter (slug, locale, documentId) already has a description. The main description references slug and documentId conceptually but adds no new meaning beyond the schema. Since the schema fully documents the parameters, a baseline of 3 is appropriate.

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

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

The description states a precise action (fetch one document) with specific resource (support document owned by the authenticated organization) and distinguishes itself from sibling tools like search_documents or list_documents by emphasizing 'one' document. It also names the returned fields (article text, contentFormat), making the tool's role 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 clearly implies usage for fetching a single document by slug or ID, and mentions the bounded 'not found' result for documents owned by other organizations. While it doesn't explicitly contrast with alternative tools (e.g., list_documents for listing), the single-document focus is evident. The cross-organization note adds useful context for when this tool is appropriate.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: the per-website preview is capped at 100 and reports truncation, and sensitive identifiers are never returned. This is useful beyond annotations and has no contradictions.

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 front-load the primary action and follow with essential behavioral details. Every sentence carries information, with no redundancy or fluff.

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

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

Given there are no parameters and an output schema exists, the description fully explains the key behaviors an agent needs: what is counted, how grouping works, the preview cap, truncation reporting, and privacy guarantees. Nothing essential is missing.

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

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

The tool has zero parameters, so the schema covers everything (100% coverage). The description does not need to explain parameters; a baseline of 4 is appropriate for parameter-less tools.

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 ('Count'), a precise resource ('unresolved conversation'), and a grouping dimension ('by website') within an authenticated organization. This clearly distinguishes it from siblings like list_conversations (which lists conversations) and get_conversation (which retrieves a single one).

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 context is clear: it counts unresolved conversations grouped by website, which implies its use when aggregate numbers are needed rather than individual conversation details. However, it does not explicitly name alternatives or state when NOT to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond by detailing which sensitive fields are excluded (org ids, prompts, credentials, integration config, arbitrary metadata) and uses the term 'safe metadata,' providing behavioral guarantees not present in the annotations.

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

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

Two sentences with no redundancy. The core action and scope come first, followed by a clear exclusion list. Every word adds value; the structure is efficient and front-loaded.

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

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

With a single well-documented parameter, an output schema available, and annotations covering the safety profile, the description fully specifies what the tool does and what it never returns. An agent has all necessary information to invoke it correctly without additional inference.

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

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

The input schema fully describes the parameter ('Website id or exact name'), covering 100% of schema description. The description adds contextual meaning by clarifying that the website must be owned by the authenticated organization, which helps interpret the parameter's domain. This is a modest addition 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 a specific verb ('Fetch') and resource ('safe metadata for one website') plus a scope restriction ('owned by the authenticated Supovia organization'). It explicitly lists what is never returned, which distinguishes it from broad list tools like list_websites and other getters like get_conversation.

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 specifies the context (one website owned by the authenticated org) and implies that this tool is for single-website retrieval, contrasting with list_websites for all websites. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already cover readOnly, idempotent, and nondestructive. The description adds valuable behavioral context: it returns only campaign identities (not full objects), is bounded by pagination, and explicitly excludes content fields and sending capability. This goes beyond the safety annotations to set precise expectations about output scope.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and then lists exclusions. There is no fluff or redundancy; every clause earns its place by clarifying scope and what the tool does not do.

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 output schema exists (documenting return structure) and annotations cover safety, the description sufficiently covers scope, exclusions, and limitations. Nothing an agent needs to decide whether to call this tool is missing; the bounded page, website ownership, and inability to send are all stated.

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 covers all parameters (limit, cursor, websiteId) with descriptions, so the baseline is 3. The description adds context about the result being identities and bounded pages, which indirectly relates to limit/cursor, but it does not provide specific parameter syntax or additional semantics beyond the schema. It neither fills a coverage gap nor adds significant meaning beyond what the schema already documents.

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 'campaign identities' for a specific scope: one website owned by the authenticated Supovia organization. It explicitly lists exclusions (recipient lists, subjects, content, ids, metadata) and clarifies that sending is not possible, distinguishing it from sibling send tools. This is specific and 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 provides context: requires a websiteId for a website owned by the authenticated org, returns a bounded page, and cannot send campaigns. It does not explicitly name alternative tools for acquiring full campaign details, but the exclusions imply that if content is needed, another tool must be used. This is clear enough but lacks explicit 'use this when' instructions relative to siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations by specifying the response is a bounded page, ordered newest-first, and explicitly listing exclusions (message bodies, message ids, customer identifiers, internal notes, arbitrary metadata, organization ids). This gives the agent a precise expectation of what to look for and what to ignore.

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, dense paragraph that front-loads the core purpose and immediately states the scope and constraints. Every clause contributes: what it does, what it returns, and what it excludes. There is zero fluff, and the structure makes the most critical information appear first.

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 presence of a full output schema and four optional parameters, the description is sufficiently complete for an agent to call the tool correctly. It clarifies the boundary of the response (what is included and excluded) and implies pagination via 'bounded' and the cursor parameter. The only minor omission is an explicit note about pagination behavior (e.g., how to request the next page), but the output schema likely covers this.

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% – all four parameters (limit, cursor, resolved, websiteId) are fully described. The description does not add any parameter-specific meaning beyond the schema; it only mentions the overall behavior (bounded, newest-first). With full coverage, the baseline of 3 applies, and no compensation is needed.

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

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

The description states a specific verb ('list'), a resource ('conversation activity'), and a bounded scope ('newest-first page in the authenticated Supovia organization'). It also enumerates exactly which fields are returned and which are excluded, making it unmistakably distinct from siblings like get_conversation or search_documents.

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 guidance is implied rather than explicit. The phrase 'Returns only the conversation id needed for an explicit follow-up' hints that one should call this to obtain IDs then use get_conversation for details, but it does not explicitly contrast against other listing tools or state when not to use it. This meets the 'implied usage' bar, not the higher 'clear context with exclusions' level.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context by specifying ordering (newest-first), bounded page size, and fields excluded (content, embeddings, prompts, etc.), which goes beyond the annotations and clarifies the tool's 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?

A single, dense sentence that front-loads the key action (List a bounded newest-first page) and then specifies scope and exclusions. Efficient and easy to parse, with 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?

The output schema exists, so return details are not needed. The description covers what is included and excluded, plus ordering and scope. It lacks explicit mention of pagination mechanics, but that is implied by 'cursor' in the schema and 'page' in the description.

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 80% (4 of 5 params have descriptions). The description does not elaborate on any parameters, so it relies on the schema. This meets the baseline for high coverage, but does not add extra 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?

The description clearly states the action (list), the resource (support-document metadata), and the scope (bounded newest-first page in the authenticated Supovia organization). It also distinguishes itself by listing exclusions (content, embeddings, etc.), which sets it apart from search_documents and get_document.

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 for retrieving metadata without content, and the 'bounded newest-first' aspect suggests pagination. However, it does not explicitly mention when to choose this over search_documents (e.g., 'use search_documents for keyword queries') or provide conditions for not using it.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds that only safe identity and status fields are returned, excluding prompts, credentials, integration config, org ids, and metadata—valuable context about the response's security boundary beyond annotations.

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

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

Two concise sentences with no redundancy. The core action and scope are front-loaded, and the exclusions are stated efficiently. 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?

An output schema is present, so return values are covered. The description addresses pagination, scope, and security-related exclusions. It could mention error behavior or explicit authentication, but 'authenticated' is included. For a read-only list, this is nearly 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 50%; the cursor parameter has a description, but limit does not. The description mentions 'bounded page' which implies pagination, but it doesn't explain the limit's range or purpose. The cursor is already documented in the schema, so the description adds minimal semantic value for the 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 ('List') with a resource ('websites') and scope ('authenticated Supovia organization'), and notes it returns a 'bounded page'. This clearly distinguishes it from get_website and other list_* siblings by resource.

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

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

No explicit guidance on when to use this tool versus alternatives. It does not name sibling tools or conditions (e.g., use get_website for a single website). The purpose is clear but usage context is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable context: it is app-only, reads no thread, and explicitly lists what it does not return (message body, preview, message id, customer detail, internal note). This goes beyond the annotation baseline and helps set expectations without contradicting the annotations.

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

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

The description is extremely concise, consisting of two sentences with zero fluff. It front-loads the primary purpose and immediately adds a clarifying clause about what it does not do. Every sentence earns its place, making it easy to parse quickly.

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 a single parameter and an output schema (present), and annotations cover safety. The description explains the tool's scope and excluded content, which is good. However, it omits any explanation of the conversationId parameter, which is essential for a correct call. Given the low schema coverage, this is a notable gap, leaving the description only partially complete 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%, meaning the conversationId parameter has no schema-level documentation. The description fails to explain what conversationId represents, its format, or how it should be obtained. This is a critical gap for an agent calling the tool, as it must infer the meaning from the tool name 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 clearly states the tool's function: refreshing safe activity metadata for a single conversation in the embedded Supovia inbox. It is specific about the resource and action, and it clarifies what it does not return, which helps distinguish it from content-fetching tools. However, it does not explicitly differentiate from sibling tools like get_conversation or list_conversations, so it lacks explicit 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 implies usage by noting it is app-only and returns no thread content, suggesting it should be used when the agent needs to refresh metadata without content. It does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusion conditions or prerequisites. The context is implied but not formally stated.

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

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

The description goes well beyond the annotations. While the idempotentHint annotation already signals idempotence, the description elaborates ('re-sending the same state is a no-op write'), adds that it 'broadcasts a conversation-updated event to the operator dashboard', and guarantees that 'customer identifiers, staff ids, and organization ids are never returned'. This provides critical behavioral context that the annotations alone do not cover.

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 tight and well-structured: three sentences, each adding distinct value. It leads with the core action, then explains idempotency, then the event broadcast and privacy guarantee, and finally restricts scope. No wasted words; front-loaded with the essential 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?

For a simple state-toggle tool with only two parameters and an output schema present, the description covers all necessary aspects: the action, the idempotent behavior, the side effect (event broadcast), and the privacy boundary. It also clarifies the tool's limited scope. Nothing essential is missing for an agent to invoke 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 100%: both parameters (conversationId and resolved) have detailed descriptions in the input schema. The description merely paraphrases 'resolved/reopen' without adding syntax, format, or default information. Per calibration, baseline is 3, and the description adds no extra parameter meaning.

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 function: 'Mark one organization-owned Supovia conversation resolved, or reopen it.' It specifies the resource (conversation), the action (resolve/reopen), and the scope ('No other conversation field can be changed'). This distinguishes it from other conversation tools in the sibling list, making its purpose unmistakable.

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 context by stating it can only change the resolved field, but it does not explicitly identify alternatives or when to use them. It fails to mention, for instance, that get_conversation is for reading or open_customer_inbox_conversation for opening. The guidance is implicit rather than direct, so it earns a 3.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context by specifying the return cap of 5 safe document identities and explicitly excluding content chunks, embeddings, scores, prompts, and metadata—information an agent needs to know about the tool's output before calling 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 sentence that front-loads the purpose (search published support documents) and follows with the key constraint (returns at most 5 safe document identities, exclusions). Every word earns its place—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?

All parameters are covered by the schema, the output schema exists (so return values are documented structurally), and the description fills gaps such as the return cap and exclusions. The tool is self-contained and includes enough sibling differentiation to guide correct invocation. Nothing an agent needs to call it correctly 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 coverage is 100%, with each parameter (query, locale, websiteId) having a description in the schema. The tool description adds no additional information about parameter usage beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('search'), a clear resource ('published support documents'), and the scope ('one organization-owned Supovia website'). It is clearly distinct from sibling tools like list_documents (which lists documents) and get_document (which retrieves a specific document) because it is a semantic search operation.

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 clearly implies usage for finding relevant documents by query on a specific website, but it does not explicitly state when not to use this tool or reference alternatives. The context is clear enough for an agent to infer it should be used for search rather than listing or retrieval, but explicit exclusions are missing.

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?

The description adds valuable behavioral details beyond annotations: 'The result confirms the target and time without returning a message id or echoing the message body.' It also clarifies the idempotency semantics (same conversation and text) and the organization-owned scope. This complements the idempotentHint and destructiveHint annotations without contradiction.

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 that front-load the core action and follow with the critical idempotency constraint and response behavior. No extraneous words or repetition.

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, combined with a rich input schema and an output schema, fully equips an agent to invoke the tool correctly. It covers the idempotency behavior, the response limitations, and all required parameters. No additional information is needed for correct usage.

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 each parameter is already documented (content, conversationId, idempotencyKey). The description adds nuance about idempotencyKey reuse but largely restates what the schema says ('Stable unique retry key for this exact conversation and reply text'). Since the schema does the heavy lifting, a baseline of 3 is appropriate.

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

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

Clearly states the verb 'send', the resource ('operator reply in an organization-owned Supovia conversation'), and the idempotent nature, which distinguishes it from all read/list siblings in the tool list. The description leaves no doubt about what action this tool performs.

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 guidance on idempotencyKey reuse ('Reuse the same idempotencyKey only when retrying the same conversation and text'), which is a key usage rule. It does not explicitly name alternative tools or when not to use it, but given all sibling tools are read/list operations, the intended use is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable behavioral context: it explicitly lists what the tool does NOT receive (message bodies, previews, message ids, customer details, internal notes) and clarifies it reports only the unread count with metadata. This goes beyond the annotations and provides a clear boundary of data exposure. No contradiction 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?

The description is two sentences long with zero wasted words. The first sentence front-loads the primary purpose and scope, and the second sentence explicitly lists exclusions in a clear, structured manner. Every clause carries meaning, and the description is easily scannable 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?

Given the tool has no parameters, an output schema (which likely details return format), and comprehensive annotations, the description is complete. It specifies what the tool reports (unread count), what data it includes (conversation ids, channel, status, unread count, timestamps), and what it excludes (message bodies, previews, etc.). An agent has everything needed to invoke and interpret the result without ambiguity.

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 zero parameters, so the input schema is empty. The baseline for 0 parameters is 4, and the description adds no parameter-specific semantics because there are none. It does describe the output elements (conversation ids, channel, status, unread count, timestamps) which are relevant for the agent's understanding of the tool's behavior, but since no parameters exist, there is nothing further to document.

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 ('open') and resource ('metadata-only Supovia inbox') and clearly defines the output: a count of conversations with unread activity. It also enumerates the data elements included and excluded, which differentiates it from sibling tools like list_conversations or open_customer_inbox_conversation without needing to name 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 implies usage for a lightweight, metadata-only overview of unread activity, and explicitly notes it never passes message bodies or details, suggesting a precursor step for follow-up. However, it does not explicitly state when to prefer this over sibling tools like list_conversations or show_support_overview, nor does it mention any alternatives or exclusion conditions. The context is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds valuable context by disclosing that the output excludes sensitive identifiers, internal notes, and credentials, which is beyond 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?

The description is a single sentence that front-loads the purpose and then lists exclusions. It is efficient and well-structured, though it could benefit from a break into two sentences for readability.

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 output schema covers return format, and annotations cover safety. The description provides scoping and exclusion details, making it complete for an overview tool. The term 'recent' is somewhat vague but acceptable in this 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?

The schema fully documents the only parameter (websiteId) with a clear description, so the description adds no extra semantics. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool renders a bounded organization-scoped snapshot of websites and recent conversations, which is distinct from sibling list tools like list_websites or list_conversations. It also enumerates what is excluded, adding precision beyond the tool name.

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 this is for a high-level overview, but it does not explicitly state when to prefer it over siblings or mention exclusions. No when-not-to-use guidance is given, leaving selection partly to inference.

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