SuperBot

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true, so the safety profile is covered. The description goes beyond them by stating the real-world impact ('changes future visitor-facing answers') and the additive/non-destructive scope ('never edits or deletes existing training'). The duplicate-suppression sentence largely restates idempotentHint, which is why this is a 4 rather than 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?

Five short sentences, front-loaded with the action and effect, followed by preconditions and then boundaries. Nothing is redundant padding: each sentence either states scope, a precondition, or a behavioral limit.

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 return values need not be explained. The description covers effect on future answers, the pre-call verification step, and the non-destructive/idempotent boundaries, which is everything an agent needs to invoke a 3-parameter write 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%, so the schema already documents question, answer, and category with lengths and examples. The description reinforces that text must be user-approved but adds no format, syntax, or constraint detail beyond what the schema supplies — the baseline 3 for a fully documented 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?

Specific verb+resource: 'Add a user-approved question/answer pair to this workspace's SuperBot training.' It names the object (training entry), the required input shape, and even the sibling tool (search_knowledge) that an agent might confuse it with, so it is separable from the read-oriented siblings without opening a schema.

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

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

Explicit preconditions and routing: 'Confirm the exact text with the user and check search_knowledge first,' plus an exclusion ('never edits or deletes existing training'). This tells the agent both when to call it and what it cannot be used for, which is exactly the guidance a write tool needs.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real behavioral context: hard caps of 500 messages / 60,000 characters, the presence of truncation flags, and a dashboard URL for the full history. It does not mention auth/permission requirements or error behavior on an unknown id, so it is strong rather than exhaustive.

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

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

Two sentences, zero filler, with the retrieval action and id provenance front-loaded before the return characteristics. 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?

The tool is simple (one required param), annotations carry the safety profile, and an output schema exists so return-value documentation is not the description's burden. The description still adds the practical limits and truncation behavior an agent needs, leaving no meaningful 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?

With one parameter and 100% schema description coverage, the schema already documents the id fully (including maxLength 64 and UUID provenance). The description's note that the id comes from other tools largely restates the schema's 'Conversation id (UUID) from another SuperBot tool', so baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve one support conversation by the id') and immediately distinguishes itself from siblings by naming the four tools that produce valid ids. An agent can tell this apart from search or list_recent_conversations without opening any schema.

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

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

Explicitly tells the agent where the required id comes from (search, list_recent_conversations, list_unanswered_questions, list_training_gaps), which is exactly the routing information needed. It does not state when *not* to use it or what to do if the id is stale/invalid, so it falls short of full when/when-not 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 readOnly, idempotent, non-destructive, so safety is covered; the description adds genuinely useful behavioral context instead of repeating it — the window is always compared against the previous equal-length window, and topics are keyword themes from opening messages rather than a classifier, which warns the agent against over-trusting them. It does not mention pagination or result size limits beyond the 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 dense opening sentence front-loads purpose and payload, followed by short usage and caveat sentences. It is long but nearly every clause carries distinct content (each metric named is a separate return field), so little 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?

With read-only annotations and an output schema present, the description need not document return shapes, yet it still tells the agent what the analyst view contains and warns about the topic-classification caveat. The only gap is that it never positions the tool against its closest sibling for a reader choosing between them.

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%, with both `days` and `topics` fully documented including ranges and defaults, so the baseline is 3. The description reinforces the comparison-window meaning of `days` but adds no new syntax or semantics beyond what the schema already states.

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 (analyst view of this workspace's support) and then enumerates exactly what is returned: recurring topics with trend, repeated questions, volume and escalation change, AI fallback rate, CSAT/sentiment change, answer sources, and a daily volume series. That level of output enumeration makes it unmistakable against siblings like get_support_overview or list_recent_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?

Gives concrete trigger phrases ('what are customers asking about', 'what's trending') and a cadence context (weekly/monthly support review), plus a follow-up instruction to read examples with fetch before concluding. It stops short of stating when to prefer a sibling like get_support_overview or list_unanswered_questions instead, so no explicit exclusion is 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered without description help. The description adds genuine context that the result is workspace-scoped and window-bounded, but the metric enumeration largely restates what the output schema already carries, so it exceeds the annotation baseline modestly rather than substantially.

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 with zero filler: capability and scope first, the intended use case second, the alternative routing last. Every clause earns its place and the most decision-relevant information is 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?

For a read-only aggregate with a full output schema and complete annotations, the description supplies everything needed to select and call it: what it aggregates, the window parameter's role, the workspace scope, and when to prefer get_insights. No return-value explanation is required given the 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents the days range (1-365) and default of 30. The description's "over a window of days" reinforces rather than extends the schema; baseline 3 is correct.

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 (aggregate) and resource (support health for this workspace) and enumerates the concrete metrics returned: volume, open/pending/closed, CSAT with sample size, sentiment split, busiest channels. It also explicitly contrasts itself with get_insights, so an agent can separate the two without opening either schema.

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

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

Gives both a positive trigger ("Use it to answer 'how is support doing'") and an explicit routing rule with the alternative named and the conditions that select it (topics, period-over-period trends, AI answer quality -> get_insights). Nothing 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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that results can reveal failed or stale sources, which hints at the lifecycle states returned. However, since an output schema exists, the enumerated return fields largely duplicate structured data rather than adding new behavioral context, so this sits at the baseline.

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 dense sentences, front-loaded with the resource and its returned fields, then the usage guidance and the sibling routing. Nearly every clause earns its place, though the field enumeration partially restates the output schema and could be trimmed.

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-required-parameter list tool with full annotation coverage, a rich output schema, and 100% schema coverage, the description supplies enough routing and intent context to invoke it correctly. The only minor gap is that it does not mention the filter parameters an agent could combine with it, though the schema covers those adequately.

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

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

Schema description coverage is 100%, so limit, cursor, status, and source_type are each documented in the schema with ranges, defaults, and examples. The description mentions 'type' and 'status' only as returned fields, not as filterable parameters, and adds no syntax or semantic detail beyond the schema. Baseline 3 applies.

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

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

Names a specific verb and resource ('List the knowledge sources'), immediately scopes it to the workspace's SuperBot agent, and enumerates the returned fields (type, status, entry count, last sync time, trained Q&A count). It also explicitly distinguishes itself from search_knowledge, so an agent can route correctly without opening schemas.

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

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

Gives three concrete use cases ('audit what the AI knows', 'spot failed or stale sources', 'what have we taught the bot') and names the alternative tool with the condition that selects it ('To search inside the content, use search_knowledge'). This is explicit when-to-use plus when-not-to-use.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), lowering the bar. The description adds real value beyond them: default ordering (newest first), the returned field set (name, email, phone, company, source, status, score, notes) and a data-handling constraint about not pasting personal data publicly.

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 that are front-loaded with the core list+resource+ordering, then filters, then usage. The field enumeration and privacy reminder make it slightly dense but every clause carries information; nothing 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?

An output schema exists, so return values need no further explanation, and all six parameters are schema-documented. Purpose, ordering, returned fields, filter surface, example intents and a privacy caveat are all present, leaving no material gap for a read-only list tool.

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

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

Schema coverage is 100%, so each parameter is already documented in the schema (including cursor semantics and exact-match sources/statuses). The description only restates the filter dimensions at a high level, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

Specific verb (list) and resource (sales leads in SuperBot CRM), with scope (this workspace, newest first) and the lead origins enumerated (chat contact sharing, workflow/form, manual). An agent can distinguish this from list_recent_conversations or search_knowledge without opening the schema.

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

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

Gives concrete use cases ('who asked for a quote this week', lead follow-up review) and names the filter dimensions that select them, which orients the agent well. It does not name an alternative sibling (e.g. search) or state when-not-to-use, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world semantics, so the safety burden is lifted. The description still adds genuine behavioral context beyond them: result ordering (newest first), workspace scoping, and that status filtering is optional. Pagination behavior is left implicit, which is documented in the cursor param.

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 no filler: scope and ordering are front-loaded, and the routing hint is appended rather than buried. 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 exists, so return-shape details are correctly omitted, and the description covers scope, ordering, filtering, and when to prefer this over search. The only gap is that pagination is never hinted at in prose, though the cursor parameter documents it fully.

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

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

Schema description coverage is 100%, including limits, cursor semantics, and an enum for status, so the schema does the heavy lifting. The description only restates that status filtering is optional and adds no syntax or default details 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?

States a specific verb and resource ('List the most recent support conversations in this workspace') with ordering ('newest first') and the optional status filter. It also carves out its territory against the sibling search tool ('rather than searching for specific words'), so an agent can route without opening a schema.

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

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

Explicitly gives the use case ('what came in today') and contrasts it with word-based lookup, which effectively points at the `search` sibling. It does not address other plausible siblings such as list_unanswered_questions or get_support_overview, so the routing guidance is clear but not exhaustive.

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, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: the filtering rule that greetings and very short messages are excluded, and the fact that answer_feedback is computed over the same window as the gap signals.

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 first clause, and the rest is dense with distinct facts (signals, return composition, workflow, exclusion rule). It is slightly long, and the detailed enumeration of return contents partly duplicates the output schema, but no sentence is 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 complex analytical tool with an output schema, annotations, and fully documented parameters, the description supplies everything an agent still needs: what counts as a gap, the exclusion rule, the pagination hint, and how to act on the results via sibling 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 100%, so days, limit and cursor are already fully documented in the schema, including defaults, ranges and cursor semantics. The description only contributes the 'same window' tie between the lookback and answer_feedback, 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 precise verb+resource ('Find questions the AI could not answer well') and then enumerates the exact signals that qualify a question as a gap: AI fallback replies, human escalations, and 1-2 CSAT ratings. That specificity distinguishes it from vaguer siblings such as list_unanswered_questions, which only covers one of those signals.

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

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

It gives a clear decision context ('Use it to decide what to teach next') and names the follow-on tools and order of operations (check search_knowledge, draft, then add_trained_answer). It stops short of explicitly stating when NOT to use this tool versus list_unanswered_questions, which appears to be a close sibling.

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the result ordering, and the warning that results are leads rather than confirmed failures — a semantic nuance annotations cannot express. It does not describe pagination behavior, though the cursor param and output schema cover that.

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 purpose and ordering, then the caveat and remediation workflow. Dense and mostly waste-free, though the final sentence on list_training_gaps is a long clause that a tighter routing pointer could carry.

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 annotations covering the safety profile, a fully documented schema, and an output schema handling return values, the description supplies exactly the missing layer: how to interpret the results and what to do next. Nothing an agent needs to call it correctly is absent.

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?

All three parameters are fully described in the schema (coverage 100%), so the schema does the heavy lifting and the baseline of 3 applies. The description adds no format or range detail beyond what the schema already states.

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 recent conversations that may still need an answer') plus the triage framing, and explicitly contrasts itself with list_training_gaps, which covers the demonstrably-unanswerable case. An agent can distinguish it from list_recent_conversations and list_training_gaps without opening any schema.

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

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

Gives ordering semantics (escalated first, then open/pending), an explicit interpretive caveat ('a lead to check, not proof the AI failed'), a follow-up workflow (read the transcript with fetch, check search_knowledge), and names the alternative tool for a different question type. When/when-not and alternatives are all present.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: result ordering ('newest first'), the fields returned (id, title, dashboard URL), and the recommended next call. It does not discuss pagination behavior directly, though the schema's cursor field covers that.

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 tight sentences: what it searches and returns first, then the follow-up tool, then the exclusion case. Zero filler and each sentence carries distinct 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?

An output schema exists so return values need not be spelled out, and the annotations cover the safety profile. The description still supplies scope, ordering, and tool routing, leaving nothing an agent needs in order 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 100%, so limit, query, and cursor are all documented in the schema itself (including literal, case-insensitive matching semantics). The description's mention of searchable fields marginally reinforces the query parameter but adds no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (Search) plus resource (customer support conversations) and enumerates the searchable fields (subject, visitor name/email, message text). This is clearly distinguishable from siblings like search_knowledge or list_recent_conversations without opening either schema.

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

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

Explicitly routes the agent: use `fetch` with a returned id for the full transcript, and use `list_recent_conversations` when the goal is 'what came in recently' with no keywords. Both the follow-up path and the exclusion condition are named.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the workflow context that this is a pre-write lookup and that results span two domains, but says nothing about result ordering, matching behavior beyond what the schema states, or cost/latency. Useful but thin against an already-complete annotation set.

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

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

Three short sentences with no filler: scope first, then the motivating use case, then the routing alternative. Every sentence carries information the 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?

An output schema exists, so return structure need not be explained, and the description covers scope, use case, and the nearest alternative. The only minor gap is that it does not hint at the two-list result shape or how a caller should treat partial matches, which matters for a search tool, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so limit, query, and cursor semantics (literal case-insensitive matching, page size, cursor chaining) are already fully documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description names a specific verb (search) plus the two concrete resource domains it covers (trained question/answer pairs and ingested knowledge sources), and explicitly distinguishes itself from the sibling list_knowledge_sources. An agent can tell what this returns without opening the schema.

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

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

It states the exact decision context ('check whether an answer already exists before writing a new one', i.e. before add_trained_answer) and names the alternative tool with the condition that selects it ('to list all knowledge sources and their sync status, use list_knowledge_sources'). This is explicit when-to-use plus a named alternative.

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