Clueforge

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered; the description still adds real value by stating the output shape (text preview + hosted link), the post-call instruction ('Always show the returned link to the user'), and the validation rules that will cause rejection (single-word answers 2–15 letters, each solution letter in a distinct answer, answer not in its own clue). It does not clarify that puzzle creation on the server side is still read-only in effect, which is the one ambiguity left.

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 purpose and return value, then use cases, then a tight 'Rules:' block of hard constraints, ending with the one imperative agents must not skip. Every sentence carries either selection guidance or a rejection condition.

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, yet the description still tells the agent what the response is for and what to do with the link, and it covers the input rules that determine a successful call. Nothing needed 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 two enums are self-documenting, so baseline would be 3. The description goes beyond it by documenting cross-parameter constraints the schema cannot express: each letter of solution_word must occur in a different answer, add clues if a letter is missing, and the solution word must not be used as an answer.

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+resource ('Builds a crossword puzzle') and immediately adds the distinguishing mechanics: a hidden solution word derived from clue/answer pairs, plus a text preview and a clue-forge.com link. No sibling tools exist, so there is nothing to disambiguate against, and the scope is fully legible.

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?

Explicitly names intended use cases ('personalised puzzles (birthday, wedding, couples, Valentine's Day, Christmas, classroom, team events) or general-knowledge puzzles'), which steers selection well. It lacks an explicit 'when not to use' clause, but with no sibling tools that omission costs little.

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