hashtag_tools

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

With no annotations, the description carries the full burden and succeeds admirably. It discloses mode-specific details: extract returns offsets, remove tidies whitespace, generate uses stop-word-filtered frequency, and format supports four styles. The Unicode-awareness note (#日本語 works) is an important edge-case disclosure that exceeds typical behavior descriptions.

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 sentences, zero filler. The mode list is front-loaded and each mode is described with compact but sufficient detail. The final Unicode note is a single sentence that adds critical capability information. Every word earns its place.

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

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

Given the tool's complexity (4 modes, 6 params, no output schema), the description covers all modes and key behavioral nuances. It lacks explicit return shapes (e.g., exact structure of offsets, whether generate returns an array), but these are partly inferable from phrasing ('with offsets', 'suggest #hashtags', 'normalize an array'). It is slightly incomplete without output schema, hence not 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?

Schema descriptions already cover parameter-to-mode relationships (e.g., 'For generate', 'For format'), so the baseline is 3. The description adds value by explaining the mode enum itself and providing algorithmic detail (stop-word-filtered word frequency) and Unicode behavior, which gives deeper semantic meaning beyond the schema.

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

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

The description clearly states 'Hashtag operations on text' and enumerates four distinct modes (extract, remove, generate, format) with specific verbs and outcomes. This distinguishes it from all sibling tools, which are general text utilities, and makes the tool's purpose immediately obvious.

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 context for when each mode is appropriate by defining what it does, but it does not explicitly name alternatives or state when not to use it. Since no sibling tool overlaps with hashtag-specific operations, the lack of explicit exclusions is acceptable. The mode enumeration implicitly guides usage.

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