GraphChinese: Chinese dictionary and grammar

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered structurally. The description adds the corpus provenance ('Counted over GraphChinese's 145 graded readings'), which is meaningful context for interpreting the frequency data, though it says nothing about pagination limits or result-set bounding 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?

Three sentences, front-loaded with the resource and its return shape before the usage routing. The enumeration of returned fields is dense but every element carries selection value; only minor tightening is possible.

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

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

With no output schema, the description carries the return-value burden and does so completely, enumerating item fields and the summary coverage thresholds. Combined with full annotation coverage and 100% schema coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so count and offset are already fully documented in the schema, making 3 the appropriate baseline. The description adds no syntax or interpretation detail for these parameters beyond what the schema provides; the 50/80/90/95 percent figures describe output, not inputs.

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

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

States a specific verb+resource ('List the most frequent Chinese characters') plus the exact ordering and per-item fields returned (pinyin, meaning, HSK level, cumulative coverage share). It also names a sibling it is not (lookup_word), so an agent can route without opening a schema.

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

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

Gives the explicit trigger condition ('when the user asks which characters matter most or how many they need') and an explicit exclusion with the correct alternative ('Do not use it for one character's meaning (use lookup_word)'). Both when-to-use and when-not-to-use are covered.

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. The description still adds real behavioral context beyond that: the list is prerequisite-ordered rather than arbitrary, and each entry carries a summary plus the slug that get_grammar_point consumes, which tells the agent this call feeds a follow-up lookup.

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 doing distinct work: what the tool returns, why the order matters, when to use it and when not to. The distinguishing ordering detail is front-loaded rather than buried.

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

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

With no output schema, the description carries return-shape duty and does so by naming the two fields the agent will receive (summary and slug) and the tool the slug feeds. Combined with annotations covering the read-only profile and a fully documented schema, nothing needed to call it correctly or consume the result 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 both parameters (level 1-6, count 1-20 default 10) are fully documented in the schema. The description adds nothing about parameter format or defaults; mentioning the 'slug' concerns the return payload, not the inputs. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List the grammar points of an HSK level') plus the distinctive ordering semantics ('in the order GraphChinese teaches them, which respects what each point needs first'). It also names the sibling it must not be confused with (get_grammar_point), so an agent can separate the two without opening either schema.

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

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

Gives both sides explicitly: use it 'when the user asks which sentence patterns to learn first, or what grammar to study at their level', and 'Do not use it to explain one pattern (use get_grammar_point)'. The alternative and the condition that selects it are spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context the annotations do not: the shape of the returned payload (explanations, examples with pinyin/English, per-word notes, prerequisites, and follow-on points) and the input-provenance constraint. With no output schema, that return-shape disclosure earns credit beyond the annotation baseline.

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

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

Three sentences, front-loaded with the core action and slug requirement, then expected output, then routing. The return-value enumeration is long but justified given the absence of an output schema; no sentence is filler.

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

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

For a single-parameter read tool with no output schema, the description covers what is fetched, what comes back, when to call it, and where valid inputs come from. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents the slug format and its origin. The description nevertheless reinforces provenance by warning not to guess a slug and naming the two tools that produce valid ones, which adds operational meaning beyond the regex and maxLength constraints.

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 ('Get one Mandarin grammar point by its slug') and immediately distinguishes it from its nearest sibling by tying it to search_grammar. An agent can identify this as the detail-fetch companion to the search tool without opening the schema.

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

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

Gives explicit when-to-use context ('after search_grammar, when the user wants a pattern explained or wants to know what to study before it') and an explicit prohibition ('Do not guess a slug'), naming the two sibling tools that supply valid slugs. This is routing guidance an agent can act on directly.

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. The description adds substantive scope disclosure beyond that—components, containing characters, confusable look-alikes, sound-component family, and words—which tells the agent what the call actually yields. It stops short of noting any limits on result size or ordering.

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 purpose, then the returned relation types, then usage. Three sentences, each carrying distinct information, with no filler or repetition 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?

There is no output schema, so the description properly carries the burden of describing what is returned, and it does so thoroughly. Combined with a fully documented single parameter and benign read-only annotations, an agent has everything needed to select and invoke this correctly.

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

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

Schema coverage is 100% and the single parameter is already documented as 'Exactly one Chinese character', so the baseline is 3. The description earns an extra point by restating the boundary in operational terms ('Do not use it for words of two or more characters'), which disambiguates the maxLength=4 input against multi-character word lookups.

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?

Opens with a specific verb and resource ('Show how one Chinese character connects to others') and then enumerates the exact relation types returned. It is clearly distinguishable from siblings like lookup_word, search_dictionary, and get_topic_words, which serve different retrieval goals.

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

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

Gives three concrete use cases (learn a character through its parts, disambiguate look-alikes, explore a character family) and an explicit exclusion ('Do not use it for words of two or more characters'). Nothing about when to pick this over a lookup tool is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context the annotations cannot: the result is ordered pedagogically rather than sorted, and each entry is a themed group carrying pinyin and meaning. It stops short of saying how many lessons are returned or whether the set is capped/paginated.

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 with a distinct job: what it returns, what kind of ordering it is, and when to use or avoid it. No filler, no restatement of the title, and the routing constraint comes last where it is easy to find.

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

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

With no output schema, the description carries the burden of describing the return shape, and it does so reasonably ('themed group of words with pinyin and meaning'). For a one-parameter, low-complexity read tool this is nearly sufficient; the only omitted detail is the volume/limit of lessons the caller should expect.

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 already documents 'HSK level, 1 to 5' with min/max bounds. The description only restates the same 1-to-5 range, adding no format, default, or edge-case semantics beyond the schema. Baseline 3 applies when the schema does all the work.

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 (get the opening vocabulary lessons of an HSK level) plus the organizing principle (GraphChinese teaching order, themed groups with pinyin and meaning). It explicitly negates a common misreading — 'a learning order, not an alphabetical word list' — so an agent can separate it from search_dictionary and get_topic_words without opening any schema.

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

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

Gives an explicit when-to-use ('user asks what words to learn first, or what to start with at HSK 1 to 5') and an explicit when-not-to-use with the named alternative ('Do not use it to look up one word (use lookup_word)'). This is the strongest form: trigger condition plus routing exclusion.

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. The description adds genuinely useful behavior beyond that: the no-argument mode returns a 30-item topic/slug list, and the normal mode returns pinyin, meaning and HSK level per word.

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 what the tool returns, then the zero-argument discovery mode, then the inclusion/exclusion rule. No sentence is filler.

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

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

With no output schema, the description carries the burden of describing return values and does so (pinyin, meaning, HSK level). Annotations cover the safety profile, and the single optional parameter's dual behavior is explained, leaving no material gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond by spelling out the no-topic behavior (30 topics and their slugs) and reinforcing that topic is a slug-like selector. It still does not clarify the slug pattern or max length beyond what the schema already documents.

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

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

The description states a specific verb and resource ('Get the core Chinese words for a topic') plus the concrete return fields (pinyin, meaning, HSK level) and example topics. It also differentiates itself from the dictionary-style siblings by excluding translation of a specific 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 gives a clear when ('the user wants words for a situation or subject'), a clear when-not ('Do not use it to translate a specific word'), and a discovery path ('Call it with no topic to list the 30 topics and their slugs'). The alternative tool for single-word translation (lookup_word/search_dictionary) is not named explicitly, so routing still requires mild inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds value by disclosing the return payload (pinyin, meanings, HSK level, alternate readings, character breakdown, teaching lessons), which is meaningful since there is no 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?

Front-loads the verb+resource before the return list and the usage conditions. Every sentence carries information (scope, returns, when-to-use, when-not), though the return enumeration is somewhat long for a single-parameter tool.

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

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

With no output schema, the description compensates by enumerating return fields, and for a one-parameter read-only tool it leaves nothing an agent needs to call it correctly. The language exclusion also closes an obvious 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?

Schema description coverage is 100%, so the 'word' parameter is already documented with an example. The description adds a small but useful constraint by noting input may be simplified or traditional characters, which the schema does not state.

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 Chinese word or character), plus scope (single word, simplified or traditional). It doesn't explicitly name the nearest sibling (search_dictionary), so an agent must infer the lookup-vs-search boundary, but the core purpose 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?

Provides an explicit when-to-use trigger ('when the user asks what a specific Chinese word means or how it is pronounced') and a when-not boundary ('Do not use it for Japanese or other languages'). It does not name search_dictionary as the alternative for finding unknown words, so the routing is clear but not fully exhaustive.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, so safety is covered, and the description goes further by disclosing the result cap ('up to 10 matching words') and the per-result fields (pinyin, meaning, HSK level, link). No output schema exists, so this return-shape detail is genuinely load-bearing; only pagination/ordering behavior remains unspecified.

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, all earning their place: purpose/inputs first, return shape second, routing exclusions last. No filler, no 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?

For a single-param read-only lookup with no output schema, the description supplies everything an agent needs: query forms, result cap, result fields, and routing against siblings. Nothing material 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?

There is a single required parameter and schema description coverage is 100%, so the schema already documents the accepted input forms. The description restates the same character/pinyin/English acceptance without adding format or syntax detail beyond the schema, matching the baseline 3 for a fully documented param.

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 (a Mandarin Chinese dictionary) and enumerates the accepted query types. It also names the scope limit (headwords, not sentences), which lets an agent distinguish it from segment_text and search_grammar without opening any schema.

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

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

Gives explicit when-to-use ('user wants the Chinese for an English word, or does not know the exact headword') and when-not-to-use ('whole sentences (use segment_text) or grammar questions'), each with a named alternative. Nothing about selection is left to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds behavior the annotations do not: what a result contains (a one-paragraph summary and a slug for get_grammar_point), which is real chaining information. It does not mention pagination or result caps, so it falls short of a 5.

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

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

Three tight sentences, front-loaded with scope and filter modes, then return shape and handoff, then the exclusion. Every clause, including the vocabulary-tool warning, earns its place with no redundancy.

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

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

With no output schema, the description carries the return-value burden and does it (summary paragraph plus slug). A zero-required-parameter search tool is fully specified: scope, filter modes, keyword vocabulary, output shape, and the sibling to call next.

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, but the description goes beyond the schema by enumerating what qualifies as a keyword: English (comparison, passive), a Chinese marker (把, 了), or a term name. That is genuinely additive, though it does not elaborate on the level parameter beyond the schema's own wording.

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 (195 Mandarin grammar points) plus the two filtering axes (keyword, HSK level, or both). It explicitly names the sibling get_grammar_point and the handoff artifact (the slug), so the agent can distinguish it from lookup/search tools without opening any schema.

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

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

Gives an affirmative trigger ("Use this to find which grammar point covers a pattern") and an explicit exclusion ("Do not use it for vocabulary questions"), and routes the agent onward to get_grammar_point via the returned slug. This is the when/when-not/alternative pattern in full.

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 cover the safety profile (readOnly/no destructive/openWorld), and the description goes well beyond them: it discloses the exact return payload (word order, dictionary pinyin, short meaning, HSK level, per-HSK-level counts) and warns that pinyin is the dictionary reading rather than a sentence-specific one. That caveat is exactly the kind of behavioral trait an agent cannot get from structured fields.

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?

Four short sentences, front-loaded with the action and the return shape, ending with the usage boundary. No filler, no restatement of the title, and every sentence carries information an agent needs.

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

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

With no output schema present, the description carries the return-value burden and does so fully (per-word fields plus HSK-level counts), while annotations handle the safety profile. Nothing material for correct invocation appears to be 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?

Only one parameter and schema description coverage is 100%, with maxLength/minLength already documented in the schema. The description adds only the loose framing of 'sentence or short passage' and no syntax, encoding, or format guidance beyond what the schema states, 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?

Specific verb + resource: 'Split a Chinese sentence or short passage into words.' It also frames the boundary against a plausible competing intent ('Do not use it to translate a whole passage'), which differentiates it from translation-oriented behavior an agent might otherwise assume.

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 two concrete use cases ('gloss a sentence word by word', 'judge how hard a text is') and one explicit exclusion ('Do not use it to translate a whole passage'). It stops short of naming a sibling tool (e.g. lookup_word, search_dictionary) as the alternative, so routing between siblings still requires inference.

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