Brainiall NLP

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. The description adds useful behavioral context: the engine, sub-10ms latency, domain-specific variants, and the exact return contract. No contradiction with annotations 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 well-structured with Args and Returns sections, and it fronts the core behavior in the first line. The engine/latency note is slightly promotional but still useful for selection. Overall, it is concise with minimal redundancy.

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

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

For a read-only inference tool with no output schema, the description sufficiently covers inputs, model variants, and return keys with types and confidence-score semantics. It omits error behavior and edge cases, but the schema and annotations cover the main invocation constraints. An agent can call this tool correctly with the given information.

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 already documents text and model with descriptions, defaults, and maxLength at 100% coverage. The description's Args section largely mirrors the schema without adding new semantic detail. The baseline of 3 applies because the schema carries the parameter documentation burden.

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

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

The description names a specific verb and resource ('Analyze text sentiment') and clarifies the task as binary positive/negative classification, which distinguishes it from aspect-level sentiment analysis. It does not explicitly name sibling tools, but the scope is clear and specific enough for an agent to identify the tool's purpose.

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

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

The description provides no guidance on when to use this tool versus aspect_sentiment, classify_text_custom, or other siblings. The model variants ('general', 'financial', 'twitter') are parameter choices, not tool-selection guidance. An agent would have to infer usage context from the tool name and sibling list.

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 non-destructive behavior. The description adds meaningful behavioral details beyond these: the six output categories, score range 0.0-1.0, BERT-based model, sub-15ms latency, and the is_toxic flag indicating threshold exceedance. This substantially enriches the annotation data.

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

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

The description is well-organized with a summary, score overview, and formal Args/Returns sections, making it easy to scan. It repeats the category names in both the introductory list and the Returns block, introducing minor redundancy, but every section contributes useful 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?

Since there is no output schema, the description fully specifies the return dict with keys and value types, including the is_toxic flag. It also covers model behavior and latency. Minor gaps include the undisclosed threshold for is_toxic and lack of edge-case behavior for empty or very long input, though maxLength is in the schema.

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

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

Schema description coverage is 100%, and the single 'text' parameter is already described in the schema as 'Text to analyze for toxicity (hate speech, insults, threats)'. The description's Args section merely repeats this definition and adds no new constraints, format details, or interpretation beyond what the schema provides.

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

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

The description opens with 'Analyze text for toxic content', a specific verb and resource, and enumerates six toxicity categories, making its scope precise. This clearly distinguishes it from sibling tools like analyze_sentiment and classify_text_custom, which serve different classification purposes.

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 conveys a clear use case: detecting toxic content across specific categories. However, it does not explicitly mention alternatives or state when not to use this tool. The context is evident, but no exclusionary or decision-rule guidance is provided.

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 set openWorldHint=true, while the description explicitly restricts the tool to 'ONLY the supplied text' and promises 'found:false rather than guessing.' This is a direct contradiction with the annotations, triggering the annotation-contradiction rule despite otherwise useful behavioral details such as supporting spans and null answers.

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 key constraint is front-loaded in one sentence, and the Args/Returns layout is easy to scan. Some redundancy with the schema's parameter descriptions is minor and does not harm 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?

For a two-parameter read-only tool with no output schema, it supplies the return dictionary shape, the no-guess behavior, and character-offset details, which is nearly complete. The only notable gap is reconciling the conflicting openWorldHint annotation with the closed-text claim.

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% and the Args section mostly repeats the schema descriptions. No significant additional meaning is added beyond 'text' being the document and 'question' the query, so the baseline score of 3 applies.

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

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

States a specific verb ('answer'), scope ('using ONLY the supplied text'), and what is returned (supporting sentence(s) with character offsets). This clearly separates it from sibling tools like knowledge_query or summarize_text.

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

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

The phrase 'using ONLY the supplied text' and 'Replies found:false rather than guessing' define clear usage context for grounded extractive QA. However, it never names a sibling alternative or states when not to use other text tools, so no explicit routing is provided.

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 the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral detail about the internal process: sentence splitting per aspect, classification, and aggregation. It doesn't cover edge cases or return format, but it goes meaningfully beyond 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 short and front-loaded with the core purpose, followed by a compact process summary. The 'Brainiall Aspect Sentiment engine' sentence is filler, but it doesn't materially bloat the description.

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

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

For a two-parameter NLP tool, the description covers the operation well, but there is no output schema, and the description does not specify the return shape, sentiment scale, or how aggregation is represented. It is adequate for basic selection and invocation, but not fully self-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?

The schema covers both parameters fully with descriptions and an example for 'aspects'. The description adds some context by clarifying that the text is split into sentences mentioning each aspect, but it doesn't significantly change or deepen understanding of the parameters themselves, 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 clearly identifies aspect-level sentiment classification as the core function and gives a concrete process: split text into sentences mentioning each aspect, classify, aggregate. It distinguishes itself from generic sentiment analysis through the 'per aspect' scope, though it doesn't explicitly name a sibling.

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

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

The phrase 'Sentiment per aspect' implies the appropriate use case, but the description never says when to choose this tool over analyze_sentiment or any other sibling. No exclusions or alternatives are mentioned, so the agent must infer usage context.

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 that this is read-only, idempotent, and non-destructive. The description adds useful behavioral context by specifying the return payload—grounded, confidence, supporting_span, reason—which is especially valuable because no output schema is present.

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 compact and front-loaded: the first sentence states the purpose directly, and the second provides the return format. There is no filler or duplication of schema fields.

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

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

For a two-parameter, read-only tool with strong annotations and no output schema, the description is sufficient. It explains what the tool does, what inputs are expected, and what the response will contain, making it complete for invocation purposes.

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 both claim and source are already documented with clear meanings. The description mostly restates these concepts instead of adding new parameter-level detail, so it does not elevate the semantics 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 identifies the tool's core operation: verifying whether a claim is supported by a given source text, framed as a hallucination check. It is specific and distinct from general text analysis siblings, though it does not explicitly name or differentiate itself from alternatives.

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

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

The usage context is implied through the 'claim vs source text' framing, but there is no explicit guidance on when to choose this tool over related siblings like answer_question or knowledge_query. No exclusions or alternative routing are provided, so the agent must infer applicability.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context by detailing the return structure: status ('healthy' or error state), models per capability, and API version. This clarifies what 'health' means without contradicting 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 compact and front-loaded with the core purpose, followed by a concise bulleted return structure. Every sentence provides useful information with no redundancy.

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

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

For a parameterless health-check tool, the description is complete: it states the purpose, the return keys, and expected value shapes. The existing annotations cover safety and idempotency, and no output schema is needed given the explicit return documentation.

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 there is no parameter semantics burden on the description. The description appropriately focuses on return values rather than input handling.

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 ('Check health status') and a concrete resource ('NLP API services and loaded models'). It is clearly distinct from the sibling NLP processing tools, which perform analysis or detection rather than service health monitoring.

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 intended use is clear: check the health of the NLP service and its loaded models. There is no explicit when-not-to-use or alternative mention, but none of the sibling tools serve a similar health-check purpose, so the context 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 readOnly and idempotent hints, and the description adds valuable behavioral detail: it explicitly states the zero-shot nature, that no training or data upload occurs, and it discloses the return shape ({top_label, scores, confidence}). Since there is no output schema, this return format disclosure is especially informative.

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 compact and front-loaded: the first sentence conveys the core purpose and differentiator, and the second line adds the return format. Every clause earns its place with 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?

The description is complete for this tool's needs. It covers return values (since no output schema exists), relies on a fully documented input schema, and the annotations handle safety and idempotency. An agent can correctly select and invoke the tool with the information provided.

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 text, labels, and multi_label all already documented. The description adds no new parameter-level detail beyond the schema, so the baseline score of 3 applies.

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

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

The description states a specific verb+resource: zero-shot text classification with user-defined labels at call time. The phrase 'define your labels at call time' clearly differentiates this from sibling classifiers like analyze_sentiment or analyze_toxicity, which use fixed, predefined label sets.

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 a clear use case: custom classification without training or data upload, which signals when to use this over purpose-built classifiers. However, it does not explicitly name alternatives or state when not to use the tool, 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds genuinely useful behavior beyond annotations: cross-turn coreference and the rule that 'Same surface text + type across turns gets the same entity_id.' The 'Brainiall Conversational PII engine' sentence is branding noise, but the entity_id disclosure earns the score.

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 core purpose is front-loaded in the first sentence, and the entity_id detail is a compact high-value addition. One sentence ('Brainiall Conversational PII engine.') carries no informational value and costs a point.

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

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

There is no output schema, and the description does not explain what the tool returns beyond implying entity_ids — an agent cannot anticipate the response shape (entity types, positions, confidence scores). With one well-documented parameter and safety annotations covering behavior, this is adequate but has a real gap around return semantics.

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

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

Schema description coverage is 100% — the schema already documents turns as 'List of [role, content] dicts representing a dialogue.' The description's entity_id rule pertains to output behavior, not parameter meaning, so the baseline 3 applies without the description needing to compensate.

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

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

The description states a specific verb and resource ('Multi-turn PII detection') and adds a distinguishing behavior ('cross-turn coreference') that sets it apart from the sibling detect_pii. The entity_id stability rule further clarifies exactly what this tool does that its single-turn sibling does not.

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 'multi-turn' qualifier and 'cross-turn' language imply this tool is for dialogue contexts, presumably as opposed to detect_pii for single texts. However, no alternative is named explicitly and no when-not-to-use condition is stated — the routing 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?

The description goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing the model (fastText), language count (176), latency (sub-1ms), and a detailed return structure including ISO 639-1 codes and confidence scores. This gives the agent a clear expectation of behavior and output format, fully leveraging the absence of an output schema.

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

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

The description is well-structured with a brief intro paragraph, followed by Args and Returns blocks. Every sentence contributes: the intro gives purpose and key capabilities, the Args explain parameters (even though redundant), and the Returns clarify the output shape. It is front-loaded with the purpose and keeps details organized, with no fluff.

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

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

Given that there is no output schema, the description's detailed Returns section is essential and it covers it thoroughly. It also communicates performance characteristics and language coverage. For a simple, read-only tool, this is complete: the agent knows what to input, what to expect, and what the result looks like.

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 already provides complete descriptions for both 'text' and 'top_k' (100% coverage), and the description's Args section merely reiterates them without adding new meaning such as allowed formats, constraints beyond maxLength, or edge-case behavior. The default for top_k is also already in the schema. Thus the description adds no extra semantic value over what the schema provides.

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

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

The description opens with a clear verb-resource statement: 'Detect the language of text.' It is unmistakably distinct from sibling tools like sentiment analysis or translation, and the scope (176 languages, ISO codes) further reinforces its specific purpose.

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

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

The description does not explicitly name alternatives or say 'use this instead of X,' but the specificity of the task (language detection) is self-evident given the sibling list. It also mentions sub-1ms latency, which hints at performance-conscious use cases. However, it lacks explicit when-not-to-use guidance, so it's not 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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral detail beyond those annotations, such as the BERT-NER + regex ensemble approach and the redaction output behavior. It does not discuss model limitations or edge cases, but for a read-only detection tool the disclosure 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: a front-loaded summary, an Args section, and a detailed Returns section. It is somewhat verbose and the Args section duplicates schema descriptions, but each section is scannable and contributes to the agent's understanding of the tool.

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

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

With no output schema, the description fully documents the return structure, including keys, types, offsets, confidence scores, and redaction behavior. It also covers the input and optional redaction flag. For a read-only PII detection tool, this is sufficiently complete 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%, so the schema already documents both parameters. The Args section mostly restates the schema, though the Returns section clarifies the practical consequence of setting redact=true. This is a solid baseline-3 case: no parameter meaning is missing, but the description adds little 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 and resource: detect PII in text, and explicitly lists the PII types covered (email, phone, SSN, credit card, IP, person name). It is specific and unambiguous, but it does not explicitly differentiate itself from the sibling tool detect_conversational_pii, so it stops short of a 5.

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

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

The description gives clear usage context: call this tool when text needs PII detection, with an optional redaction mode. It does not explicitly state when not to use it or how to choose between detect_pii and detect_conversational_pii, but the capability statement is direct enough that an agent can infer the primary use case.

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, openWorldHint=true, and destructiveHint=false, so the safe, side-effect-free profile is covered. The description adds value beyond annotations by disclosing the output contract (category, severity, reason, confidence) and the open-world nature of the input. It does not contradict 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 tight sentences. The purpose is front-loaded in the first sentence, and the return structure is listed compactly in the second. There is no fluff or redundant restatement of the title — appropriate brevity for a single-purpose classifier.

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

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

For a one-parameter classifier with 100% schema coverage, comprehensive safety annotations, and no output schema, the description adequately discloses the input, the output contract, and the intended timing of use. The only minor gap is not explicitly routing the agent away from overlapping detection siblings, which is mitigated by the clear category list.

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% — the single `prompt` parameter is fully documented in the schema, including the important 'NOT executed' caveat. Per the baseline rule for high coverage, the description doesn't need to add parameter detail, and the tool objectively adds nothing beyond the schema here.

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

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

The description states a specific verb and resource — 'Classify a prompt before it reaches your LLM' — and enumerates the exact output categories (jailbreak, prompt_injection, data_exfiltration, impersonation, none), which clearly differentiates it from sibling detectors like detect_pii, detect_protected_material, and analyze_toxicity. The title 'Prompt Shield (Jailbreak / Injection Detection)' reinforces the specific purpose.

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

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

The phrase 'before it reaches your LLM' provides clear context for when to invoke this tool — it is a pre-flight safety gate. However, the description never names alternatives or gives explicit when-not-to-use guidance, even though several sibling tools (detect_pii, detect_protected_material, analyze_toxicity) occupy adjacent detection space.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the description need not repeat safety. It adds value by disclosing the return behavior ('Returns matched spans with source attribution'), which is not present in the schema. The description aligns with the annotations and provides useful behavioral context beyond them.

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 compact and front-loaded: the first sentence states the core function and examples, and the second adds the return behavior. The phrase 'Brainiall Protected Material engine' is slightly redundant branding, but it does not detract significantly. Overall, every meaningful piece of information is presented efficiently.

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

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

For a single-parameter, read-only detection tool, the description is largely complete: it says what is detected, and because there is no output schema, it properly explains the return format as matched spans with source attribution. It could mention the absence of matches behavior or length limits, but the schema covers maxLength and the description is sufficient for most agent decisions.

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

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

The schema already documents the single parameter 'text' as 'Text to scan for copyrighted material' with 100% coverage. The description reinforces this with examples of what constitutes protected material but does not add new parameter-level information such as encoding requirements or format nuances. 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 identifies the resource ('copyrighted text in user input') and the action ('detect'), with concrete examples that delineate it from sibling analysis tools like detect_pii and detect_prompt_injection. The specificity of 'famous lyrics, literary openings, proprietary code' makes the purpose unmistakable, and the sibling list confirms this is a distinct detection category.

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

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

The description implies the use case ('Detect copyrighted text in user input') but does not explicitly state when to use this tool over alternatives, nor does it give exclusion criteria such as 'for PII use detect_pii'. The examples imply the domain, but an agent would need to infer when this is the correct choice among the many sibling detection tools.

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 value beyond these by disclosing sub-50ms latency and the BERT-NER model basis, as well as providing a detailed return structure with confidence scores. This supplemental context enriches the agent's understanding without contradicting 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 well-structured: a clear opening sentence, a brief method note, and a systematic Args/Returns section. It is longer than strictly necessary, but given the absence of an output schema, the detailed return documentation is justified. The core purpose is front-loaded, making it 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?

With no output schema, the description fully specifies the return dictionary structure, including entity fields, types, offsets, and confidence scores. Given the single parameter and simple input, the description covers all necessary context an agent needs to call the tool and interpret results. Combined with annotations, this is complete.

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

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

Schema coverage is 100% and the schema already describes the 'text' parameter. The description restates the arg without adding new semantic detail (e.g., encoding, preprocessing). Per the rubric, a baseline of 3 is appropriate when the schema fully documents the parameter and the description adds no additional 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 opens with a specific verb and resource ('Extract named entities (NER) from text') and explicitly lists the entity types (persons, organizations, locations, miscellaneous). This clearly differentiates it from siblings like extract_key_phrases and detect_pii, which target different tasks. The purpose is unmistakable even 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?

The description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. However, the clear purpose implies the appropriate use case (entity extraction), and the sibling list offers context. Since no explicit guidance is given, it falls to implied usage, warranting 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 and idempotentHint, and the description adds valuable behavioral context: the algorithm uses TF, position, casing, and stopword filtering, and incurs no ML cost. This clarifies what the tool does and does not do without contradicting 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 short, front-loaded with the core purpose, and every sentence earns its place. The algorithm details are useful and add context without bloat.

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 only three simple parameters, all documented in the schema, and annotations cover read-only safety and idempotency. The description adequately explains the extraction approach and ranking behavior; no critical invocation details appear 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 input schema already provides 100% coverage for all three parameters, so the description doesn't need to add much. It adds no specific parameter details beyond what the schema states, matching the baseline for high schema coverage.

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 operation: statistical key-phrase extraction returning top-N ranked phrases. It distinguishes itself from similar siblings like extract_entities by emphasizing key phrases and the pure-statistical approach.

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

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

The description indicates this is for lightweight, statistical extraction with no ML cost, which implies appropriate use cases. However, it does not explicitly state when to choose this over alternatives like extract_entities or when not to use it.

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

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

Annotations already flag readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds that feedback is used for model recalibration and includes return keys, which is useful, but it does not clarify what `accepted: false` means or discuss side effects. There is no annotation 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?

The description is compact, well-structured into Args and Returns, and leads with a clear purpose sentence. The Args section duplicates the schema, but it is brief enough not to feel bloated.

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 simple parameter set and high schema coverage, the description is largely complete. It includes return value shape, which is important because there is no output schema. It could be slightly more complete by explaining the `accepted` boolean, but this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents event_id, label, and notes. The description's Args section restates these without adding new meaning, achieving the baseline for high schema coverage.

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

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

The description states a specific action ('Report the confirmed outcome of an event') and a clear resource (the event outcome), with the purpose of recalibrating the fraud model. This distinguishes it from the sibling fraud_score tool, which presumably produces initial scores rather than consuming confirmed outcomes.

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

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

The phrase 'confirmed outcome' clearly implies this tool is for post-event feedback rather than initial scoring, and the purpose of recalibration gives the agent context on when it is appropriate. However, it does not explicitly name alternatives or state when not to use this tool, so the guidance relies on 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, idempotentHint, and non-destructive behavior, so the bar for behavioral disclosure is lower. The description adds useful behavioral details: all signals are optional, and the output includes a fraud probability, risk level, decision, and per-factor breakdown. 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?

The core purpose and input flexibility are front-loaded, and the return structure is clearly laid out. There is minor redundancy between the prose return summary and the 'Returns:' dict-keys list, but the description remains appropriately sized for a tool with 18 parameters.

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

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

For a read-only scoring tool with no required parameters and no output schema, the description adequately supplies the return contract and input expectations. It could additionally explain risk_level/decision_bands semantics or point to fraud_feedback, but the provided detail is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 18 parameters. The description adds only a general statement that all signals are optional, which is already implied by default nulls. There is no meaningful per-parameter semantic value added 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 uses a specific verb and resource: 'Score a transaction or account event for fraud risk.' This clearly distinguishes it from the sentiment, toxicity, and PII siblings, and is also obviously different from fraud_feedback, which is about feedback rather than scoring.

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

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

The description gives clear usage context: use it when you need a fraud risk score for a transaction or account event. 'Send whatever signals you have — all optional' also tells the agent when it is acceptable to call with partial data. It does not explicitly name alternatives or exclusions, but this is a distinctive tool among the 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses meaningful side effects: the document is chunked, embedded, and stored, and a doc_id with n_chunks is returned. It does not mention duplicate handling or namespace creation, but the core persistence behavior is 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?

The one-line overview is front-loaded, followed by a compact Args/Returns section that covers the remaining useful information without fluff. Every sentence earns its place.

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

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

With no output schema, including the return keys is essential and present. The description gives enough about the ingestion pipeline for an agent to calibrate expectations. Minor gaps like whether re-ingesting the same text creates duplicates or how namespaces are created are secondary for a managed-RAG ingest 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 description coverage is 100%, so all three parameters are already documented in the schema. The Args block simply restates namespace/text/title with terse descriptions and adds no additional constraints, examples, or edge-case guidance.

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

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

The description opens with a concrete verb and resource: 'Ingest a document into a knowledge base', followed by the managed-RAG behavior (chunked, embedded, stored). This clearly distinguishes it from sibling read tools like knowledge_query and knowledge_list_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?

It establishes clear context: use when you have document text to store in a namespace for later retrieval. It does not explicitly list when-not-to-use conditions or name alternatives, but the read/write split among siblings makes the intended use obvious.

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, so the safety profile is covered. The description adds useful behavioral context about ordering ('most recent first') and the general return shape, but it does not disclose pagination, limits, or behavior for an invalid namespace. With annotation coverage, a middle score is appropriate.

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 short, front-loaded with the main action, and easy to scan. The Args and Returns sections are slightly redundant with the schema and surrounding tool definition, but the overall length is still appropriate.

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

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

This is a simple tool with one required, well-documented parameter and strong safety annotations. The description covers the key return structure and ordering, though the '...' leaves additional document fields unspecified. Given the low complexity, the description is nearly complete for invocation purposes.

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

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

The schema already describes the namespace parameter fully at 100% coverage, and the description simply restates 'The knowledge-base namespace' without adding constraints, defaults, or examples. Per the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the verb and resource: 'List the documents stored in a knowledge base' with the additional specificity of 'most recent first.' It is easy to distinguish from sibling tools like knowledge_ingest or knowledge_query, though it does not explicitly name or contrast them.

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

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

There is no explicit guidance about when to use this tool versus alternatives such as knowledge_query or knowledge_ingest. The usage context is only implied by the purpose; no exclusions, prerequisites, or alternative routing are provided.

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 safety (readOnlyHint, idempotentHint, destructiveHint=false) and openWorldHint. On top of that the description adds real behavioral context: the refusal-to-guess semantics (found:false), the grounding constraint on the synthesized answer, the rerank/synthesize toggles and their effects, and the full return dictionary shape. That goes beyond what structured annotations alone provide.

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: core retrieval behavior in the first line, then the critical failure-mode guarantee, then a compact args/returns list. No redundant prose; every sentence earns its place. Slightly more than minimal, but the extra behavioral terms (found, synthesized, reranked keys) justify the length.

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

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

A 5-parameter tool with rich retrieval/synthesis semantics is thoroughly covered: inputs, outputs, defaults, and groundedness caveats are all stated. Remaining gaps are minor and nice-to-haves — no worked example, no note on what happens when rerank or synthesis fail, no pagination/latency costs — and none prevent a capable agent from invoking 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 coverage is 100%, so the bar for added value is 3; the description clears it by defining the keyword-argument contract (dst, fields, values), while the description explains defaulting and clustering behavior in prose. Defaults are repeated clearly (top_k=6, rerank=false, synthesize=true), and the description gives the parameters purpose and interplay (reranking before synthesis) rather than just types.

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

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

The description opens with a specific verb plus resource ('retrieve the most relevant passages from a knowledge base') and its optional answer-generation mode, which is immediately distinguishable from siblings. The explicit found:false behavior (rather than guessing) further sharpens scope, and the args/returns list makes the 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 (knowledge-base, natural-language question, grounding) and clarifies the return behavior when no match exists, but it never names alternatives like answer_question or check_groundedness, nor does it say when not to use this tool (e.g., when an answer must be ungrounded, or when passages are not required). Context is clear; exclusions are absent.

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, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered and the description does not contradict it. The description adds the disambiguation behavior but omits details like pagination limits or the exact return shape of Q-ids. 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?

Compact and front-loaded: the core capability is the first sentence, and the disambiguation example is in the third line. Loses a point for the wasted branding sentence ('Brainiall Entity Linker engine') that does not earn its place with useful 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?

Adequate for a simple 2-parameter tool whose annotations carry the safety profile. However, there is no output schema, and the description does not specify the return format beyond implying Q-ids — an agent cannot tell whether results include confidence scores, bounding offsets, or just ids. This gap keeps it short of 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 description coverage is 100% — both text and max_entities are already documented in the schema, so baseline 3 applies. The description adds no parameter-specific detail beyond confirming the output is Wikidata Q-ids, which is more behavior than parameter semantics.

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

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

States the function clearly: named-entity recognition plus canonical linking to Wikidata Q-ids. The disambiguation example ('Apple' vs 'apple') effectively differentiates it from the sibling extract_entities, which presumably only extracts mentions. Minor deduction for the branding phrase 'Brainiall Entity Linker engine,' which adds no functional clarity.

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 context is implied rather than explicit. The disambiguation example suggests when this tool is needed (when canonical identity matters), but the description never names extract_entities as the lighter alternative or states when not to use it. No explicit when/when-not routing.

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. The description adds useful behavioral detail beyond annotations: extractive mode preserves verbatim sentences in original order, and the return value is a dict with summary plus word/char counts. No contradictions 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?

The description is compact and well-structured: a one-sentence definition, a short Args list, and a Returns line. Every part earns its place, and the most important distinction (extractive vs abstractive) 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 three-parameter, scalar-input tool, the description is complete. It documents all parameters, explains the two modes, and specifies the return shape despite there being no output schema. Annotations cover safety and idempotence, so nothing essential is missing for an agent to call this 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 text, mode, and max_length. The description mostly restates this information, adding only marginal nuance like 'original order' for extractive mode. It meets the baseline but does not substantially extend the schema's parameter documentation.

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

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

The description opens with a specific action and resource: 'Summarize text', and immediately distinguishes the two modes (extractive vs abstractive) with concrete definitions. This clearly separates it from siblings like analyze_sentiment or extract_key_phrases, none of which perform summarization.

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 purpose statement implies use when a condensed version of text is needed, but the description never explicitly says when to prefer this tool over alternatives or when not to use it. No sibling is mentioned, so usage routing is left to inference rather than spelled out.

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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds genuine context beyond them: the auto-detect behavior of source_lang and the return shape (dict with translated_text key, plus detected source language when auto-detected). No contradiction with annotations — 'translate' is consistent with readOnlyHint as a non-destructive transform. The description enriches, rather than repeats, the 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?

Well-structured: a one-line purpose statement followed by labelled Args and Returns sections, with the purpose front-loaded. The Returns section earns its place by disclosing output format absent from the schema (no output schema exists). Minor deduction for the Args block redundantly restating schema text, which adds bulk without value.

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

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

Since no output schema exists, the description carries the burden of explaining return values — and it does, specifying the dict key and the conditional detected-language behavior. For a low-complexity tool (3 flat params, no nesting), this is nearly complete. Minor gaps: language code format is only implied by examples, and error behavior on invalid target_lang is unspecified, but these are marginal against an otherwise adequate definition.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description's Args section mirrors the schema nearly verbatim (e.g., 'source_lang: Source language code; omit to auto-detect' duplicates the schema text), adding no new meaning. Per the baseline rule, with full schema coverage a 3 is appropriate — the schema does the heavy lifting and the description adds no marginal parameter insight.

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 ('Translate'), resource ('text'), and scope ('between 100+ languages'). The purpose is unambiguous and clearly distinguishable from all siblings — none of the 21 sibling tools perform translation, so an agent can confidently select it.

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 Args section implies the usage pattern (provide text + target lang, omit source to auto-detect), but the description never explicitly routes the agent to or away from alternatives. Notably, sibling detect_language overlaps with the auto-detect behavior — the description doesn't tell the agent that pure language identification should use detect_language instead of translate_text. This is a missed opportunity for a tool with a directly overlapping sibling.

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