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

With no annotations, the description carries the full burden. It discloses a key behavioral nuance: reports visible characters separately from code points, which differ for accents and emoji. It also guarantees exact counting. This adds meaningful context beyond the title, though it does not cover edge cases like empty input.

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

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

The description is two sentences with zero filler. It front-loads the core function ('Count characters, words, lines, sentences and bytes') and then adds usage guidance and a behavioral nuance, all in a compact structure.

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 one-parameter tool with no output schema, the description covers the main operational aspects: what is counted, precision, and the visible-character/codepoint distinction. It does not explicitly state the return format or handle edge cases, but the described behavior is sufficient for an agent to invoke it correctly.

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

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

The input schema already describes the 'text' parameter with 100% coverage, so the baseline is 3. The description does not add further parameter-specific detail, such as encoding or size limits, so it neither enhances nor detracts from the schema.

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

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

The description explicitly states the tool counts characters, words, lines, sentences, and bytes, with a specific verb and resource. It also emphasizes exactness and distinguishes from token-based reading, making the purpose unambiguous even without naming siblings.

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

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

The description provides clear guidance on when to use the tool: 'whenever the answer needs to be a precise number.' It also explains why ('reading tokens is not the same as counting characters'). It does not explicitly list alternative tools or exclusion conditions, so it stops short of full when/when-not coverage.

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 no annotations provided, the description carries the full burden. It discloses the tool's outputs (unified diff, line counts, similarity percentage) and its read-only nature implicitly. It does not list limitations or side effects, but since this is a pure comparison function, the disclosed behavior is adequate and clear.

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

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

The description is two sentences with zero filler. The core behavior is stated first, followed by a direct usage recommendation. It is efficient and front-loaded, earning a perfect score for conciseness.

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

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

For a tool with three parameters, two required, and no output schema, the description adequately covers what the tool does and what it returns. It does not specify the exact diff format or similarity algorithm, but these are likely not essential for correct invocation. The description is sufficient for an agent to call this tool accurately.

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

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

The input schema provides 100% coverage with descriptions for all parameters ('original text', 'changed text', 'context lines around each change'). The tool description itself adds no additional meaning to the parameters—it only mentions the purpose in general terms. Since schema coverage is full, 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?

The description clearly states the tool's function: compare two versions of a text and return a unified diff, exact line counts added/removed, and a similarity percentage. It uses a specific verb and resource, and it differentiates from siblings by explicitly contrasting with manual description, making the purpose 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?

The description provides direct usage guidance by saying 'Use it rather than reading both versions and describing the difference,' which tells the agent when to prefer this tool over the obvious alternative. It does not discuss edge cases or exclusions, but for a simple diff tool this is sufficient context.

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

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

No annotations are present, so the description carries the behavioral burden. It does add useful traits: determinism and non-reversibility ('not something that can be worked out by reading'). However, it does not mention output encoding, the effect of the selected algorithm, or whether any side effects exist, leaving a moderately complete behavioral picture.

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 free of filler. The second sentence is slightly vague, but it contributes a behavioral distinction rather than padding, so the length and structure are strong.

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 two-parameter tool with fully described schema fields and an algorithm enum/default, the description covers the essential invocation context. It does not specify the return format, but that is a minor gap given the task's simplicity and the absence of an output schema.

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

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

Schema description coverage is 100%, so both text and algorithm are already documented in the schema. The description adds no new parameter-level meaning beyond 'some text', so the baseline score of 3 is appropriate.

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

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

States a specific action and resource: 'Compute a cryptographic hash of some text'. This clearly distinguishes it from the sibling text-analysis tools (count_text, score_readability, diff_texts, test_regex), leaving no ambiguity about what the tool does.

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

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

There is no explicit guidance about when to use this tool versus alternatives. The intended usage is implied by the self-describing operation, but the description does not state conditions, exclusions, or when a sibling tool would be more appropriate.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple one-liner by explaining not only the metrics (Flesch ease, grade level) but also that it provides a plain-language interpretation of the number and reports the longest sentence as a likely cause of poor readability. This gives the agent a clear picture of what the tool does and what it outputs, though it does not mention every detail (e.g., range of scores or edge cases).

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

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

The description is two sentences with zero filler. The main purpose is front-loaded ('Score how hard a piece of text is to read'), followed by the specific metrics and an additional behavior (longest sentence). Every sentence earns its place and the structure is highly efficient.

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 there is no output schema, the description does a good job of explaining what the tool returns: Flesch score, grade level, plain language interpretation, and longest sentence. This is sufficient for an agent to understand the tool's behavior and call it correctly. It could be more complete by specifying numeric ranges or examples, but those are not strictly necessary for correct invocation.

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

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

Schema description coverage is 100%: the only parameter 'text' is described as 'The prose to score.' The description adds minimal semantic value beyond this, only referring to 'a piece of text' and 'prose' again. Since the schema fully documents the parameter, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: scoring how hard a text is to read, with specific metrics (Flesch reading ease and grade level). It also distinguishes itself from all sibling tools (count, diff, regex, hash) by focusing on readability assessment. The verb 'score' and resource 'a piece of text' are specific and 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?

The description implies usage through its purpose: use this when you need readability metrics for prose. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or specific conditions. Since the sibling tools are clearly different (counting, diffing, regex testing, hashing), the intended use is inferable but not explicitly articulated.

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 no annotations present, the description fully carries the behavioral burden. It discloses the return content (all matches, positions, capture groups), error handling for invalid patterns, and the read-only nature of the operation. This is meaningful behavioral information beyond what the schema provides.

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

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

Three short sentences, each earning its place: the first states the core action and output, the second clarifies error behavior, and the third gives the intended use case. It is front-loaded and contains 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 simple regex-testing utility, the description provides everything an agent needs: the operation, the output shape, error handling, and the use case. There is no output schema, so the description appropriately fills that gap by explaining what the tool reports.

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

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

Schema description coverage is 100%, so the schema already documents pattern, text, and flags. The description adds a little context by mentioning positions and capture groups, but it does not need to describe parameters further since the schema already does so adequately.

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

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

The description states a specific action ('Run a regular expression against text') and a precise output ('every match with its position and capture groups'). It also distinguishes this from sibling tools like count_text, score_readability, diff_texts, and hash_text by focusing on regex behavior rather than counting, scoring, diffing, or hashing.

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 final sentence gives a clear usage context: 'Use it to check a pattern actually does what it looks like it does.' This tells an agent when the tool is appropriate, though it does not explicitly name alternative tools or state when not to use it. The context is clear enough that an agent can route to this tool for regex verification.

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