Word Orb — English vocabulary for reader glossaries

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

Annotations indicate readOnlyHint=false (possible side effects), openWorldHint=true, and idempotentHint=false. The description adds crucial behavioral details: it is heuristic (not legal), requires a Word Orb key and plan entitlement, and counts toward account quotas. This goes beyond the annotations and clarifies the side effects (quota consumption) and auth requirements.

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

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

The description is two sentences, with the purpose front-loaded and the disclaimers/requirements in the second sentence. Every sentence earns its place; there is no fluff or repetition.

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

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

The tool has only 2 parameters and no output schema. The description covers purpose, limitations, auth, and quota. It does not describe the output format, but given the simplicity and lack of output schema, this is not a critical omission. The description is sufficiently complete for an agent 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 both parameters (input and policy) are documented in the schema. The description adds no additional parameter-specific detail beyond what the schema already provides. The baseline 3 is appropriate since the schema carries the full 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 states a clear verb (Check), a specific resource (supplied text), and the outcome (content flags and reading-level estimates). It clearly distinguishes itself from the sibling tools, which are all word-lookup or generation tools, by focusing on compliance checking.

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 provides clear context: it is a heuristic check, not legal certification, and requires a key and quota. This implicitly tells the agent when to use it (for heuristic content checks) and when not (for legal compliance). It does not explicitly name alternatives, but the sibling set is obviously different, so the exclusion is clear.

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, the description discloses important behavioral traits: it 'May use stored data or AI generation,' tells the caller to 'review the result,' and notes the requirement for a Word Orb key, plan entitlement, and quota accounting. This adds substantial context beyond readOnlyHint and openWorldHint.

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 every sentence adds value: purpose, generation behavior, prerequisites/quotas, and an alternative tool. It is front-loaded with the primary purpose before constraints.

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 covers the main invocation considerations, including prerequisites, quotas, and behavioral expectations. There is no output schema, and the description does not detail the exact return structure, though 'definition' implies the expected content. This is a minor gap rather than a blocking omission.

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

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

Schema description coverage is 100%, so term and age_group are already fully documented. The description reinforces the age_group concept ('adapted to the specified age group') but does not add new syntax, formats, or parameter-specific meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Request a definition adapted to the specified age group.' It clearly states the tool's core function and differentiates it from the sibling lookup_words by noting that define_term may use AI generation. This leaves no ambiguity about what the tool does.

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 a clear intended use for age-adapted definitions and provides one explicit alternative: 'Use lookup_words to avoid generated fallback.' It does not enumerate other alternatives or exclusions, but the main condition for choosing this tool is clear.

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 behavior. The description adds valuable context beyond that: graph coverage varies, an empty result is valid, a key is required, and calls count toward quota. This helps the agent set expectations and handle empty responses correctly.

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, each carrying essential information: core operation, edge-case expectation, and auth/quota caveat. No filler or repetition of schema details.

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

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

For a one-parameter read-only tool, the description covers the operation, the possibility of empty results, and the authentication requirement. Without an output schema, a bit more detail about the response shape would be ideal, but the description 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?

The single parameter 'word' is fully described in the schema (100% coverage), so the description does not need to add much. It only reinforces the idea of tracing through the graph, which is marginal value 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?

Names a specific verb ('retrieve') and a specific resource ('existing links between an English headword and lessons or themes'). This clearly distinguishes it from the lookup/search siblings, which operate on definitions, translations, or related words rather than graph links.

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 when to use the tool: when graph-based links between a word and lessons/themes are needed. It does not explicitly mention alternatives or exclusion criteria, so an agent must infer selection from the resource description alone.

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

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

The description adds meaningful behavioral context beyond the annotations: it may call AI, requires authentication/entitlement, counts toward quotas, and tells the agent to review the result. These details are not present in the annotation block and are valuable for a non-read-only, non-idempotent tool. It does not contradict 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 three sentences and economical. It front-loads the core behavior, then adds operational constraints, then the sibling distinction. No sentence is wasted, though the ordering of 'review the result' before the auth note is slightly arbitrary.

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 covers authentication, quota impact, and the need to review output, which is helpful. However, given the tool has multiple task modes, no output schema, and no per-task behavior details, an agent cannot fully anticipate what will happen for tasks like 'retrieve', 'negotiate', or 'compliance_check'. It is adequate but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate, but it only weakly references the parameters: 'supplied text' points to 'input' and 'selected task' points to 'task'. It does not explain the task enum variants, what each task expects, or the expected format of input. This is a significant gap for a tool with zero schema-level parameter descriptions.

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

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

The description states a clear action ('Process supplied text') and result ('may call AI and return generated content'), giving the tool an identifiable purpose as an AI text-generation utility. It also differentiates from the sibling lookup_words by explicitly saying that one is for stored lexical records only. It is not a perfect 5 because 'Process' is somewhat generic and the range of tasks is only implied.

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 practical usage context: it requires a Word Orb key, counts toward quotas, and may call AI. It also provides one explicit exclusion ('Use lookup_words for stored lexical records only'), which helps an agent avoid the closest sibling. It does not exhaustively cover when to prefer other siblings like translate_word or define_term, but the guidance is sufficient for basic 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?

The annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful operational context beyond those annotations: it requires a Word Orb key, counts against quota, and warns that content availability varies. This is helpful transparency for an agent anticipating failures or costs.

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, front-loaded with the main purpose and followed by availability and access constraints. Every sentence adds distinct value and there is 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 omits important selection semantics: the schema declares zero required parameters while the description implies all three (day, track, age) are used. It also does not describe the shape of the returned lesson or what happens when content is unavailable. For a tool with no output schema and no parameter documentation, this is incomplete.

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

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

Schema description coverage is 0%, so the description bears the burden of explaining the parameters. It only restates that the lesson is 'for a day, track and age group' without defining value semantics, ranges, or behavior when parameters are omitted. The input schema's enums and bounds carry most of the 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 states a clear verb and resource: 'Retrieve an available structured lesson' and specifies the selection dimensions (day, track, age group). It is distinguishable from siblings like get_quiz or lookup_word by the resource type, though it does not explicitly differentiate from get_quiz.

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

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

No when-to-use or when-not-to-use guidance is provided, and no alternative tools are mentioned. The only practical note is 'Content availability varies,' which warns about failures but does not help an agent decide between this and get_quiz or other sibling 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=true and idempotentHint=true, so the safety profile is known. The description adds valuable behavioral context: the requirement for a Word Orb key, quota impact, and variability of content availability. This goes beyond annotations and helps the agent anticipate auth needs and inconsistent results.

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

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

The description is compact, with the primary purpose stated first and the additional constraints (key, quota, variability) in a short follow-up. No wasted words; every sentence earns its place.

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

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

For a simple retrieval tool with two parameters and no output schema, the description covers purpose, authentication, quota, and content variability. It does not describe the response format or pagination, but these are minor given the tool's simplicity and the annotations' coverage of safety.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It does tie 'day' and 'track' to the lesson context, but does not explain data types, formats, or allowable values. This provides basic meaning but leaves the agent to infer specifics, so a 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 action ('Retrieve') and the resource ('quiz questions') scoped by lesson day and track. It distinguishes the tool's purpose from siblings like get_lesson, but does not explicitly name any alternative, so it falls just 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?

No guidance on when to use this tool versus alternatives. It implies usage for retrieving quiz questions, but there is no mention of when not to use it, prerequisites (beyond the key), or how it relates to get_lesson or other siblings. The key/quota note is contextual but not a usage guideline.

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

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

Annotations already cover readOnly, idempotent, and non-destructive traits. The description adds valuable context: it requires an API key and counts toward quota, and it states that an empty result is a valid outcome. These are behavioral details beyond what annotations provide, so it earns a high score without contradicting the annotations.

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

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

The description is two sentences with no wasted words. The core action is front-loaded, and the additional caveats (auth, quota, empty result) are succinctly appended. It is appropriately sized for the tool's simplicity.

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

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

For a tool with one parameter, no output schema, and full annotation coverage, the description covers essential operational context: it mentions auth and quota constraints and warns about valid empty results. It does not explain return format, but that is not required given the simple retrieval nature. It is complete enough 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?

The schema fully documents the single parameter 'word' with a description. The description's mention of 'English headword' slightly reinforces but adds no new meaning beyond the schema. Since schema coverage is 100%, the baseline is 3, and the description does not compensate further.

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 ('Retrieve') and the resource ('available related-word data for an English headword'). It is specific enough to distinguish from generic lookup tools, though it does not explicitly name alternatives like explore_graph, so it loses a point for not differentiating among siblings.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention when not to use it, nor does it reference sibling tools or conditions that would select this over others. The only hint is 'available related-word data' which implies intent, but no explicit routing or exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable operational context: a Word Orb key is required and calls count toward account quota, plus the availability limitation. These are meaningful behavioral traits not present in the annotations.

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

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

Three short sentences with zero redundancy. The core action is front-loaded, followed by a necessary availability caveat and an auth/quota note—each sentence earns its place.

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

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

For a single-parameter, read-only lookup tool with safety annotations, the description covers purpose, auth, quota, and availability. It doesn't enumerate the exact metadata fields returned, but this is a minor gap given the tool's simplicity and the absence of an 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?

The schema only describes the parameter as 'Word to get images for', while the description refines it to 'an English headword', adding language and form specificity. It also clarifies that the tool returns metadata, not the images themselves.

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

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

States a specific verb ('Retrieve available image metadata') and a specific resource ('for an English headword'). This clearly distinguishes it from sibling lookup/search tools that focus on definitions, related words, or translations.

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

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

The description implies the tool is for fetching image metadata for a word)Skip, and notes that images are not available for every word, which is a soft caveat. However, it does not explicitly name alternatives or provide when-not-to-use guidance relative to the many sibling 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?

Discloses AI generation and caching side effects, potential inaccuracy of results, and quota/key requirements. This adds significant behavioral context beyond the annotations (openWorldHint=true), clarifying what 'open world' means in practice. 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?

Three sentences: main action first, then caveats, then alternative and requirements. Every sentence adds value, no fluff, and the key differentiator 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?

Given the tool's AI-assisted behavior, quota implications, and lack of output schema, the description covers all necessary context: what it does, when to avoid it, limitations, and operational requirements. An agent has sufficient information to decide and call correctly.

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

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

The schema fully describes the single parameter (word: 'English word') at 100% coverage. The description adds no extra semantic detail (e.g., format, case sensitivity, length limits) beyond the schema, so a 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 ('look up') and resource ('one English headword'), and explicitly distinguishes from sibling lookup_words by contrasting 'stored records only'. The purpose is unambiguous and differentiates well from the plural variant.

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?

Directly tells the agent when to use the alternative: 'Use lookup_words when you require stored records only.' This implies this tool is for when AI-assisted generation or non-stored records are acceptable, giving clear context for selection.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, and the description adds meaningful behavior beyond that: it returns found records, explicit misses, and lookup failures; optional fields and translations vary; requires an Authorization header; and counts against account quota. 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 description is information-dense and front-loaded, with the core purpose stated first, followed by limits, return behavior, and authentication. The final marketing link ('Evaluate and compare plans at...') is not necessary for invoking the tool correctly, which prevents a 5.

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 batch lookup tool with one required parameter and no output schema, the description is complete: it covers what is returned, how content may vary, authentication, quota, rate limits, and the no-generation scope. An agent has enough context to call it correctly.

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

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

The schema covers 100% of the parameter semantics, including the word pattern, length limits, max items, and free/paid maxima, so the baseline is 3. The description mostly repeats the headword-count limits and adds a 10-requests/minute rate limit, but adds little new meaning specific to the words parameter.

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

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

The description names a specific verb ('Retrieve') and resource ('stored AI-assisted English lexical records for a vocabulary list'), and the modifier 'without generating missing words' distinguishes it from generative tools. The plural 'vocabulary list' separates it from the singular sibling lookup_word.

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

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

The description clearly implies when to use the tool: for batch lookup of stored records over a list of headwords, with explicit free/paid limits and a required API key. However, it does not explicitly route the agent to alternatives like lookup_word for single words or search_words for fuzzy matching, leaving some sibling differentiation 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 adds valuable context beyond annotations: results are similarity-ranked candidates rather than verified answers, embeddings require AI processing, and the tool requires a Word Orb key and consumes quota. It does not contradict any annotation, though it could further clarify potential nondeterminism or latency implications.

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, each earning its place: purpose, result nature, and operational requirements. Information is front-loaded and no filler is present.

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 search tool with a well-documented schema, the description covers purpose, result caveats, and quota/auth requirements. The absence of an output schema and any description of return format is a minor gap, but the essential decision-making information is present.

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

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

Schema description coverage is 100%, so the schema already documents both 'query' and 'limit' adequately. The description restates the core idea of a natural-language concept query but adds no parameter-specific detail beyond the schema.

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

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

States a specific verb ('Search') and resource ('available English word embeddings') and clarifies it searches by concept description, not by exact word. The phrase 'Returns similarity-ranked candidates, not verified answers' distinguishes it from lookup/search tools among siblings.

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

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

The description implies this is for concept-based semantic search rather than exact word lookup, but it does not explicitly name sibling alternatives like search_words or lookup_word or state when to prefer them. The intended use case is reasonably clear from 'description of a concept,' but exclusion guidance is missing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond annotations: results may be empty, a Word Orb key is required, and the call counts toward account quota. This is valuable operational context with no 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?

Three short sentences, each carrying distinct information: search scope/modes, return behavior, and access/quota constraints. There is no filler, and the most important behavioral info 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?

The description plus the fully documented schema gives the agent enough to call the tool correctly: query constraints, field enum, fuzzy option, limit range, and quota impact. It does not describe the shape of matching entries, and there is no output schema, but for a simple filtered search 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 coverage is 100%, so the baseline is 3. The description adds semantic meaning beyond the schema by tying 'headwords or definition text' to the field parameter and 'prefix or fuzzy matching' to how q and fuzzy behave. This helps the agent understand parameter interactions rather than just their raw 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 clearly identifies the verb ('Search'), the resource ('stored English headwords or definition text'), and the matching modes ('prefix or fuzzy'). It does not explicitly differentiate from siblings like lookup_words or search_by_meaning, but the scope is specific enough to be understood on its own.

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 when the tool is useful: for partial-prefix or fuzzy searches rather than exact lookups. However, it never explicitly routes the agent away from alternative siblings or states when not to use this tool, so usage guidance is only implicit.

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?

Discloses key behavioral traits beyond annotations: may use stored data or AI generation, language coverage and quality vary, requires authentication/entitlement, and counts toward quotas. This adds real context not present in the annotations (which only indicate non-read-only, open-world, non-idempotent, non-destructive). No 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?

Three sentences, each earning its place: purpose, behavior/requirements, and sibling routing. Purpose is front-loaded, no filler or redundancy.

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

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

Covers purpose, behavior, prerequisites, side effects, and the key alternative. Lacks an explicit statement about return value, but for a translation request this is reasonably inferable; the absence of an output schema makes a brief mention of output format desirable, though not critical.

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 fully documents both parameters. The description adds no extra parameter-specific details beyond restating 'supplied text and a target language'; baseline 3 applies because the schema carries the load.

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

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

Clearly states the verb 'Request' and the resource 'translation' for supplied text and target language. Explicitly differentiates from the sibling lookup_words by noting that tool only inspects existing translations, so the agent can distinguish them 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?

Provides a direct alternative: 'Use lookup_words to inspect only existing translations.' This tells the agent when to choose the sibling instead. Also gives preconditions (Word Orb key, plan entitlement) and a caveat (coverage/quality vary), covering both when-to-use and 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 declare readOnly, idempotent, and non-destructive behavior, so the description doesn't need to repeat those. It adds valuable extras: that no API key is required and that content accuracy is not guaranteed. It also discloses that the word is shared for a given date, which is subtle behavioral context. This goes beyond the annotations without contradicting 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?

Two short sentences with no filler. The primary action is front-loaded, followed by the date-sharing behavior and two caveats (auth, accuracy). Every clause adds information; nothing is redundant.

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

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

For a simple read-only tool with a single optional parameter, the definition is largely sufficient. It explains the retrieval target and gives a caveat about data quality. The main gap is that it mentions 'available fields' without specifying what those are, and with no output schema the agent lacks return-structure detail. However, this is a minor gap for such a simple 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?

With 100% schema description coverage on the single optional `date` parameter, the schema already documents the format and default. The description references the date concept but adds no syntax or formatting details beyond the schema. This matches the baseline of 3 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 clearly states a specific action: retrieve the stored daily word, with a date qualifier. 'The selected word is shared for a given date' helps distinguish it from general lookup tools among the siblings, but it doesn't explicitly name any alternative. It is not a tautology and gives enough specificity to understand the resource being accessed.

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 when to use this tool (when you want the word of the day), but it does not explicitly state exclusions or alternatives. The sibling list includes many lookup/search tools, yet no guidance is given for when to prefer this over lookup_word or search_words. The 'No API key is required' note is a usage condition, not a routing rule. Usage context is present but inferred.

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