Lexpad – Vocabulary Notebook & Flashcards

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

Annotations already declare destructiveHint=false and idempotentHint=false; the description usefully reinforces additive semantics ('nothing is replaced or removed') and implies a hard prerequisite on an existing word. It does not say what happens on a duplicate meaning, whether the word_id must belong to the caller, or what an invalid word_id yields.

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, zero filler, with the core action and the additive constraint 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?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. What remains missing for a nested-object mutation tool is duplicate/error behavior and whether appended meanings affect ordering, which matters given the reorder_meanings and remove_meaning siblings.

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 only 50%, but the nested object's fields (meaning, gloss, examples) are well described in the schema itself. The description contributes real meaning by stating the meaning must be in the notebook's meaning language and that examples ride along with it, though it says nothing about word_id sourcing beyond the schema's own note.

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

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

Specific verb (adds) plus resource (one meaning) plus scope (a word already in the notebook), with the 'only adds, nothing replaced or removed' clause implicitly separating it from update_meaning and remove_meaning. It never names those siblings outright, so the differentiation is inferred rather than stated.

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?

'To a word already in the notebook' implies the prerequisite that the word must exist (create it with add_word first) and hints at when to use this over update_meaning. There is no explicit when-to-use/when-not statement or named alternative, so the agent must infer.

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?

Goes beyond the annotations by disclosing upsert semantics (existing word moves to top, only new meanings are added), the fact that everything except the headword is optional, and the language-pairing constraint between meanings and examples. This genuinely tells the agent what happens to existing data, which annotations alone (destructiveHint=false, idempotentHint=false) do not convey. It does not cover error/permission behavior.

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

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

Purpose and the card inventory are front-loaded in the first sentence, with the upsert rule last. The long clause listing card fields is dense but earns its place as a completeness cue; minor redundancy with the schema's own field list keeps it from 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?

A 16-parameter mutation tool with an output schema and annotations that already declare the safety profile; the description supplies the missing behavioral layer (defaults, upsert, language constraints). Nothing essential for correct invocation is absent, though guidance on choosing this over add_meaning/update_word would close the remaining 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 88%, so the schema already documents nearly every field including the language codes and the notebook_id default. The description adds only the optionality statement ('everything but the headword is optional') and the meaning/target language split, which the schema largely repeats. Baseline 3 fits.

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+resource ('Saves one word or phrase ... to their notebook') and enumerates the card contents, so the agent knows exactly what gets created. It also discloses the upsert behavior ('If the notebook already has the word, it moves to the top'), which implicitly separates it from add_meaning and update_word, though those siblings are never named.

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 is implied by 'the user asked to save', and the upsert sentence tells the agent it is safe to call for an existing headword. However, there is no explicit routing guidance such as 'to add a meaning to an existing word, use add_meaning' or 'to change an existing card, use update_word', which matters with 17 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds real context beyond that — the deletion cascades to meanings and their practice progress, propagates "on every device", requires the words:delete permission, and is irreversible in this context. It doesn't address behavior for an unknown word_id, but the added behavioral disclosure is substantial.

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 action and its cascade, followed by the irreversibility warning and the permission requirement. No filler or restatement of the title beyond what the action sentence requires.

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 destructive one-parameter mutation with full annotation coverage and an output schema, the description supplies what matters: scope of deletion, device-wide propagation, irreversibility, and auth prerequisite. The only gap is error/not-found behavior, which is minor given the output schema.

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

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

Single parameter with 100% schema coverage, and the schema already explains that word_id comes from another tool's result. The description adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Deletes one word from the user's notebook") and scopes the cascade ("with its meanings and their practice progress"), which implicitly separates it from remove_meaning. It stops short of naming an alternative sibling, so an agent comparing delete_word against remove_meaning or set_retired gets a hint rather than an explicit contrast.

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 irreversibility warning ("It cannot be undone here") and the permission requirement give useful preconditions for calling it, so usage is implied for genuinely unwanted words. However, it never states when to prefer remove_meaning or set_retired over deleting the whole word, and no exclusion criteria are given.

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

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

Adds genuinely non-obvious context beyond the annotations: the 'today' boundary is computed in the user's own timezone, and results are paged via next_cursor. Annotations already cover the safety profile (readOnly=true, destructive=false), so this supplemental behavioral detail earns credit. It doesn't explain ordering or why two calls may return different sets despite being a read.

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

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

A single front-loaded sentence with the core predicate first and the pagination hint parenthetical. Nothing is wasted.

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

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

With an output schema and full schema coverage, the description only needs to frame the resource and pagination, which it does. It leaves unstated whether the result set is stable within a day or how it is ordered, a minor gap for a review-queue tool.

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

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

Schema coverage is 100%, so all three parameters are fully documented in the schema, making 3 the baseline. The description reinforces the cursor mechanism and the timezone framing but says nothing about limit or notebook_id scoping that the schema doesn't already cover.

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 resource and predicate: the words due for review today, paginated. It is clearly distinguishable from get_recent_words, list_words, and get_word. It does not explicitly name a sibling alternative, which keeps it from 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?

Use is implied by 'due for review today' — the description signals the review-queue scenario without naming when to prefer get_recent_words or list_words instead. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and idempotentHint=false. The description adds useful ordering and pagination context ('newest first', 'a page at a time (next_cursor)'), but does not explain default notebook scoping or result shape beyond what annotations/schema cover.

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

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

A single front-loaded sentence with no wasted words. Ordering, pagination, and core resource are stated efficiently.

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

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

With rich schema coverage and an output schema, the description covers what the tool returns and how paging works. The main gap is not clarifying its relationship to sibling list/search tools, but that is more a usage-guideline issue than a completeness failure.

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

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

Schema description coverage is 100%, so limit, cursor, and notebook_id are already documented in the schema. The description only echoes cursor pagination via '(next_cursor)' and adds no parameter meaning beyond the schema, making the baseline 3 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 resource (words), the ordering (most recently added, newest first), and pagination. It does not distinguish this from siblings like list_words or search_words, which keeps it from 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?

Usage is only implied by 'most recently added' and 'newest first' – an agent can infer this is for browsing recent additions. There is no explicit when-to-use guidance or mention of alternatives such as list_words or search_words.

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 a read-only, closed-world, non-destructive operation. The description adds useful behavioral context by specifying that the card includes meanings, examples, collocations, notes, user progress, notebook schedule type, and smart-notebook retention probability. It lacks operational details such as error behavior when word_id is invalid.

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

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

The description is a single front-loaded sentence with no irrelevant filler. It is dense but well structured, though some detailed return-content clauses overlap with what the output schema can provide.

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 with full schema coverage, annotations, and an output schema, the description is sufficiently complete about what the card contains. It is only incomplete on when to choose this over sibling retrieval tools.

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

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

Schema description coverage is 100%, and the sole parameter word_id is already documented as an id from another tool's result. The description adds no parameter-specific meaning beyond the schema, 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 a single-word retrieval tool and enumerates the card contents, so the agent can tell that it fetches full detail for one word. It does not explicitly contrast this with siblings such as list_words or search_words, which keeps it from 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?

Usage is implied: call this when full detail for one known word is needed. There is no explicit when-to-use guidance, no mention of using another tool to obtain word_id, and no exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the useful detail that the default notebook is flagged in the result, which helps the agent pick a target notebook. It does not describe ordering or pagination, though the result set is presumably small.

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

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

A single twelve-word sentence fragment with no filler; the most decision-relevant fact (these are the user's notebooks) comes first. It would be marginally better as a complete sentence with a verb, but nothing is wasted.

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

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

With no parameters, an output schema present, and rich annotations, almost nothing else is required. The only real gap is the absence of routing guidance against notebook_stats, which matters more here than return-value detail.

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 takes zero parameters, so there are no semantics to explain and the baseline of 4 applies. Nothing in the description conflicts with the empty 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 names a specific resource (the user's notebooks) and enumerates what each entry carries: ids, languages, word counts, and the default flag. It clearly distinguishes it from list_words and notebook_stats by resource. It lacks an explicit verb, reading as a noun phrase rather than 'List all notebooks', but the intent is unambiguous.

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

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

There is no statement of when to call this versus notebook_stats or list_words, no prerequisites, and no exclusions. An agent must infer from the name that this is the discovery call for notebooks while notebook_stats handles per-notebook metrics.

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 a safe read (readOnlyHint true, destructiveHint false), so the bar is lower. The description nonetheless adds real behavioral value: total is present only on the first page, pages end with next_cursor, and cursor reuse requires identical arguments — all non-obvious traits.

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

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

Front-loaded with the resource and its scope, then pagination semantics. The filter list largely restates enum values already in the schema, which is mild duplication, but the text is dense 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?

For a 10-parameter, paginated read tool with full schema coverage and an output schema, the description covers scope, filtering, pagination and notebook selection. Return-value shape is handled by the output schema, so nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining the cursor round-trip contract and the special 'all' value for notebook_id along with the omit-for-default behavior, which helps the agent chain calls correctly.

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

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

States a specific verb and resource ('The user's words, a page at a time') and enumerates the available filter dimensions, so the agent knows exactly what the tool returns. It does not differentiate itself from close siblings like search_words or get_due_words, which overlap heavily with the filter set described here.

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?

Pagination usage is spelled out well — pass next_cursor back as cursor with the same arguments. But there is no guidance on when to pick this over search_words, get_due_words, or get_recent_words, which the agent must infer from overlapping functionality.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the useful note that the result mixes per-notebook counts with the user's overall streak, which is behavior beyond the schema. It does not clarify aggregation semantics when no notebook is given (whether counts are summed) or that idempotentHint=false despite being a read.

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

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

A single compact sentence that front-loads the scope ('Per notebook') and then lists metrics with no filler. It is slightly fragmentary — no verb — but every token carries 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?

With an output schema present, the description does not need to explain return shapes, yet it still names the key metrics so the agent can judge relevance. Annotations cover the read-only profile. Only the unstated aggregation behavior when notebook_id is omitted leaves a small 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% and the single parameter's description already explains 'omit for every notebook.' The description's 'Per notebook' framing echoes that but adds no new meaning, so the baseline 3 applies.

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

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

The description enumerates exactly what is returned — word counts broken down by state (due today, new, mastered, struggling, starred, hard to spell) plus the user's streak — so an agent can tell this is a read-only statistics tool distinct from the word-level siblings. It is a list of metrics rather than a verb+resource statement, but the resource (notebook statistics) is unambiguous.

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

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

There is no explicit when-to-use, no exclusion, and no mention of alternatives such as get_due_words or list_words, which surface overlapping data. The agent must infer from the metric list alone that this is the aggregate/summary tool rather than a listing tool.

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

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

With annotations covering the mutation and idempotency profile, the description goes well beyond that: it names the downstream effects (moves the word's box, updates the day's numbers and streak), says the result carries the next review date, and explains the practice path where scheduleChanged is false. The client_id deduplication note reinforces the idempotentHint in plain language.

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

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

Three tight sentences, front-loaded with the core action, then the side effects, then the edge case and idempotency. Every sentence carries information an agent would otherwise have to guess.

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 mutation with full schema coverage, an output schema, and annotations, the description supplies exactly what structured fields cannot: what changes in the app state, the practice/not-due special case, and deduplication semantics. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in structured fields. The description mentions client_id and its double-submit behavior, but this largely restates the schema's own description. Baseline 3 is appropriate; no meaningful syntax or format detail is added.

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

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

States a specific verb and resource: 'Records whether the user answered a practice question about a word correctly.' It is clearly distinguished from every sibling (which manage words, meanings, notebooks, or listings) and leaves no ambiguity about what calling it 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 establishes the usage context implicitly through the practice-not-due-word case, and no sibling tool competes for this action. It stops short of explicitly saying when to call it rather than, say, get_due_words, but the context is clear enough that an agent won't misroute.

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 destructiveHint annotation, the description discloses a cascade the annotations do not: the meaning's examples are removed along with it. It also reinforces irreversibility ("cannot be undone"), though that largely echoes destructiveHint=true rather than adding new information.

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

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

One sentence plus a short irreversibility warning; the object of deletion and the selection rule are front-loaded and nothing is wasted.

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

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

With annotations covering the safety profile, full schema coverage, and an output schema present, the description covers what an agent needs to invoke it correctly. It omits only edge behavior such as out-of-range index or what happens if the meaning is referenced elsewhere.

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

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

Schema coverage is 100%, with both word_id and meaning_index fully documented, so the description need not carry parameter meaning. Its phrase "chosen by its position in the word's card" restates the meaning_index documentation without adding format or off-by-one guidance beyond it.

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 (removes) and resource (one meaning, plus its examples) scoped to a word, selected by positional index. It is clearly distinguishable from siblings like delete_word (removes the whole word), update_meaning (modifies in place) and reorder_meanings.

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

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

The description implies usage by explaining the selection mechanism (position in the card, as listed by get_word) but never states when to prefer this over update_meaning or delete_word, nor any prerequisite such as confirming with the user first.

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 that this is a non-destructive mutation and not idempotent. The description adds important behavioral context: the order must list every current index exactly once, and the first item becomes the main meaning. It does not describe error behavior for invalid orders, but the core behavior is well disclosed.

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 action, and uses one concrete example to clarify the most confusing parameter. Every sentence 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?

Given the simple two-parameter mutation, rich schema descriptions, annotations, and an output schema, the description supplies the necessary conceptual context. It explains the main-meaning effect and index ordering without needing to repeat return-value details.

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 a useful concrete example, [2, 0, 1], showing how indices map to the new order and main meaning, which goes beyond the schema's prose.

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: reordering a word's meanings. It also explains the key effect, that the first entry becomes the main meaning used by practice, which distinguishes it from add_meaning, update_meaning, and remove_meaning.

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 makes the use case clear by explaining that the first meaning is the one practice asks about, implying this tool changes which meaning is primary. However, it does not explicitly contrast with update_meaning or state when not to use this tool.

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

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

The annotations already declare read-only, non-destructive, closed-world behavior, so the safety profile is covered. The description adds useful operational constraints beyond annotations: results are ranked best-first, capped at 50, and do not page or filter.

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, front-loaded with the core purpose and followed by the key behavioral constraints. There is no waste, and the most important scoping information appears first.

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

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

Given rich annotations, full schema coverage, and an output schema, the description supplies what an agent needs to invoke the tool correctly. It covers scope, ranking, result cap, and the absence of paging or filtering.

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 parameters are already well documented. The description repeats key semantics such as 'one notebook,' 'either language,' and 'at most 50,' but adds little beyond what the schema already 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 states a specific verb and resource: search words by query in one notebook, returning best matches first. It clearly distinguishes this from sibling tools like list_words and get_word by framing the operation as query-based ranked search rather than listing or retrieving by id.

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

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

It gives clear context for use: a query within a single notebook, in either language, with best matches returned first. It does not explicitly name alternatives such as list_words or get_word, nor does it state when-not-to-use this tool, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the bar is lower. The description adds the substantive consequence the annotations cannot convey: the word leaves practice but retains its progress, and the action is reversible.

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

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

One sentence, front-loaded with the primary action, with the inverse operation appended compactly. No filler or redundant restatement of the title.

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

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

With an output schema present and full parameter documentation, the description only needs to convey the state transition and its effect, which it does. Minor gap: it does not warn that retired words may still be listed/hidden in list_words results, which affects downstream tool behavior.

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 both parameters already document themselves, including the boolean's true/false meaning. The description restates the same true/false semantics rather than adding new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

Specific verb+resource ("Retires a word") with the two-way semantics spelled out ("or brings a retired word back"). It is clearly distinct from delete_word because retirement is framed as a state toggle that preserves the word, though no sibling is named explicitly.

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

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

Gives a clear selection criterion: retire a word "the user knows well enough" so it "stops coming up in practice." The un-retire direction is also stated. No explicit when-not or named alternative (delete_word vs retire) is offered, only implied by "keeps its progress."

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=false, idempotentHint=true, and destructiveHint=false, so the mutation and repeat-safety profile is covered. The description adds a genuine domain consequence — starring enrolls the word in a separate practice deck — but says nothing about permissions, failure modes, or what happens to existing deck membership when unstarring.

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 compact sentences with the action and the consequence front-loaded; every clause earns its place and nothing is padded.

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 idempotent two-parameter toggle with a full output schema, the description is essentially sufficient — action, UI analogue, and outcome are all present. Only the lack of edge-case behavior (unstarring effect on the practice deck) keeps it from 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%, including 'true to star the word, false to unstar it' on the boolean, so the schema fully carries parameter meaning. The description's 'stars or unstars' merely mirrors that mapping without adding format or constraint detail.

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 pair (stars/unstars) on a specific resource (a word), and clarifies the semantics with the UI analogue 'as the star on its card does.' This clearly separates it from neighbors like update_word or set_retired, though it does not name those siblings directly.

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 'Starred words have their own practice deck' implies why an agent would star something, but there is no explicit when-to-use guidance, no exclusion against update_word or set_retired, and no stated prerequisites (e.g., does the word need to exist?).

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 destructiveHint=true and idempotentHint=true, and the description adds genuinely new behavior: omitted fields are preserved, a supplied examples list replaces the existing one, and 'The previous text is replaced.' That clarifies the exact blast radius of the destructive hint. It stops short of stating that meaning_index doesn't shift or how an out-of-range index fails.

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 target and addressing scheme, followed by the update and replacement semantics. No filler or restatement of the title.

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

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

With a full output schema and complete parameter documentation, the description carries only the burden of update semantics, which it covers. Minor gap: nothing about failure modes for an invalid meaning_index or about interactions with reorder_meanings.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds meaning: the target is selected by position, and only supplied fields are written. It reinforces the replace-vs-merge semantics of examples and gloss beyond the per-property 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?

States a specific verb and resource ('Changes one meaning of a word') and immediately names the addressing scheme (position in the word's card) plus the mutable fields (text, gloss, examples). This clearly separates it from update_word (whole word) and add_meaning/remove_meaning in the sibling list.

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 it by explaining partial-update semantics ('Fields not given stay as they are'), but it never names alternatives such as add_meaning for new meanings, remove_meaning for deletion, or reorder_meanings for position changes. The agent must infer the boundary from the sibling names 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?

Beyond the 'destructiveHint' annotation, the description discloses critical behavioral traits: it only updates 'the fields given' (partial updates), and guarantees that 'meanings and practice progress are not touched.' This operational context is crucial for agent planning.

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 definition is dense due to the complexity of the word object (14 parameters), but it is highly structured and efficient. It front-loads the list of editable fields and immediately follows up with the operational constraints and limitations.

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 large number of parameters and the complex nature of the data structure (nested expressions/collocations), this description provides all the necessary behavioral boundaries and operational logic required for an AI agent to select and call the function correctly without ambiguity.

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

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

Even though schema coverage is 100%, the description adds significant semantic value that the schema lacks. It explains the operational rules for specific fields, such as the implications of only updating specified parameters and how previous values are replaced.

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 action ('Changes a word') and comprehensively lists all the resources/fields that can be manipulated (headword, part of speech, level, etc.). It is specific and directly relates to editing an existing word, distinguishing it from 'add_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?

It explicitly defines when to use the tool by describing which fields are editable. Crucially, it also states a key constraint: 'A headword the notebook already has is refused,' clarifying that this tool is for modifying existing entries rather than creating new ones, providing a vital boundary against the 'add_word' sibling.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds what the payload conceptually contains (account identity plus notebook count), but says nothing about auth requirements, failure behavior when no account is bound, or freshness of the notebook count; some of that is covered by the 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?

A single sentence with no filler, and the identifying resource is front-loaded ahead of the returned fields. Nothing in it is redundant or padded.

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

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

For a zero-argument, read-only introspection tool with full annotation coverage and an output schema, the definition says enough to call it correctly. Only the absence of any failure/empty-state hint keeps it below a 5.

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 takes zero parameters, so the baseline is 4 and there is nothing further the description could clarify. It correctly introduces no parameter concepts, which is consistent with the empty object 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 identifies the resource precisely — the Lexpad account this connection acts for — and names the three fields returned (id, display name, notebook count). It is a noun phrase rather than a verb+resource statement, but an agent can still tell it is an identity/introspection call and can distinguish it from the word- and notebook-oriented siblings without opening a schema.

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

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

There is no explicit statement of when to call this tool, no preconditions, and no mention of alternatives or when not to use it. The phrase 'this connection acts for' hints at a connectivity/identity check, but that inference is left entirely to the agent.

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