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

Annotations already establish this as a read-only, closed-world operation. Beyond that, the description adds real behavioral detail: tolerance semantics ('default 0, a common rule is 10'), precise exclusion rules for a References heading and for block/double-quoted text, and a statement of what is returned. It stops short of explaining edge cases like how words are tokenized or whether heading matching is case-insensitive.

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 front-loaded with the core purpose and then efficiently enumerates inputs and return values. It is somewhat dense in one paragraph and the example sentence has awkward punctuation, but no sentence 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?

Given that an output schema exists, the description need not fully specify return values, yet it still summarizes them. With annotations covering safety, six parameters documented at high coverage, and clear exclusion semantics, an agent has enough to invoke the tool correctly.

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

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

Schema coverage is already high at 83%, but the description adds meaningful semantics beyond the schema: tolerance_percent includes a practical default and a common 10% rule, exclude_references defines the exact cutoff from a heading line to the end, and exclude_quotes specifies both '>' block quotes and text inside double quotes.

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 gives a specific verb and resource: 'Compare an essay against a word limit.' It clearly separates this tool from sibling counting/diagnostic tools like count_text and readability_scores by emphasizing limit comparison, not raw counting.

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 use case is clear from 'Compare an essay against a word limit' and the example question about staying under 2000 words while excluding works cited and quotes. It does not explicitly say when not to use it or name count_text as the alternative for simple counting.

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 openWorldHint=false, so no contradiction. The description adds useful transparency beyond that: it warns the page count is an estimate from typical words-per-page and may differ slightly from a word processor, and it discloses the reading-time heuristic (238 wpm). It still doesn't mention output format or limits on text size.

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 front-loaded with the primary function, then lists inputs and defaults, then caveats and an example. It is slightly long and could trim the redundant defaults already in the schema, but every part remains informative.

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 need not explain return values, yet it helpfully notes the reading-time and page-estimate outputs. Inputs, defaults, caveats, and an example are all covered, leaving nothing an agent needs 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 75%, and the description compensates by enumerating font choices (times new roman, arial, calibri, georgia, courier new, verdana) that the schema only describes generically as a string, and by restating defaults for font_size and spacing. It adds real semantic value over the schema, though it doesn't describe constraints like the 6-72 point range.

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 specific verbs and resources: counts words, characters, sentences, paragraphs, and estimates page count and reading time. This clearly distinguishes it from siblings like readability_scores and word_frequency, but it does not explicitly separate itself from check_word_limit, which also deals with word counts.

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 a concrete example invocation ('Count the words in this essay and estimate the pages in Times New Roman 12 double spaced') and explains the default configuration clearly. However, it never states when to prefer this over check_word_limit or other siblings, so no exclusions 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context: the three formulas, how grades map to US school levels, and that SMOG results are marked less reliable on short texts. It does not fully explain the output format, but an output schema exists.

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

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

The description is front-loaded with the core purpose and is appropriately sized. Formula names, grade interpretation, input note, reliability caveat, and example each serve a clear function without repetition or padding.

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 one-parameter input schema, existing output schema, and annotations covering safety, the description provides enough context to call the tool correctly. It explains what is measured, how to interpret grades, and the main reliability caveat for SMOG.

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. It identifies the single input as 'text' and adds a relevant constraint: SMOG is intended for samples of 30 sentences or more, with shorter text marked less reliable. This is meaningful but still leaves format and language expectations unstated.

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: score text readability. It names the exact formulas (Flesch Kincaid, Flesch reading ease, Gunning Fog, SMOG), which clearly distinguishes it from siblings like count_text, style_flags, and word_frequency.

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 through the purpose and an example prompt, but there is no explicit guidance on when to choose this tool over siblings or when not to use it. The example clarifies the intended request pattern but does not provide 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 establish readOnlyHint and openWorldHint=false, and the description adds real behavioral context beyond that: the checks are simple pattern rules with false-positive risk, and the summary output ends with a line listing flagged sentence numbers. Partially overlaps with the output schema, but the caveat about rule-based imprecision is valuable and not encoded anywhere else.

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 and checks, then inputs, then output shape, then caveat — a sensible order. Slightly over-explains the sentence-numbering mechanics and the summary line, which is close to duplicating the output schema.

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 an output schema already exists, the description covers everything an agent needs: purpose, inputs with defaults, numbering convention, and the reliability caveat. Little is missing for a two-parameter read-only analysis 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 only 50%, but the description compensates: it explains that max_sentence_words is optional with a default of 30 and defines its meaning as 'the length above which a sentence counts as long'. It also names both inputs up front, leaving no ambiguity about what 'text' should contain.

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 ('Flag common style problems in an essay') and then enumerates the exact checks: passive voice, repeated sentence openers, filler words, overlong sentences. This is clearly distinguishable from siblings like readability_scores or word_frequency, which measure rather than flag.

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 interpretive directive ('treat them as prompts to reread, not as errors') plus a concrete invocation example ('Flag passive voice and filler words in my draft'). It does not explicitly name when to prefer readability_scores or check_word_limit instead, so it stops 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=true and openWorldHint=false, and the description adds real behavioral detail beyond them: case is ignored, words under 3 letters are dropped unless include_common_words is set, and each result carries a count and a share-of-text. It does not mention tokenization limits or handling of punctuation, but the added context is substantive.

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

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

Front-loaded with the purpose, then a compact parameter rundown and filtering rules. The trailing example is useful but ends with a stray punctuation artifact ("essay?."), a small blemish on an otherwise tight description.

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

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

An output schema exists, so the return format need not be spelled out, and the description still notes that each word comes with a count and a share. Combined with the disclosed filtering rules, an agent has enough to call this correctly; only edge cases like punctuation handling are absent.

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

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

Schema coverage is 75%, and the description goes further than the schema by spelling out what include_common_words actually means (the, and, of, to) and how it interacts with the short-word filtering rule. top and min_count are only restated with their defaults, which the schema already supplies.

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 (word frequency) and the intent (spot overused or repeated terms), which is genuinely distinguishable from count_text or readability_scores. It never names a sibling tool or draws an explicit boundary, so it stops short of 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?

Gives a clear usage context ("spot overused or repeated terms") and an example query ("Which words do I overuse in this essay?"), so an agent knows when this applies. It offers no when-not guidance and does not point to alternatives such as count_text.

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