tdqs / dimensions / purpose-clarity
Purpose Clarity
Does the description state what the tool does?
Summary
- level
- tool definition
- weight
- 25% of the tool score
- key
- purpose_clarity
How it is graded
Purpose clarity dominates because it is what drives selection: an agent decides which tool to call from the description alone, and a description that distinguishes the tool from its siblings is the one that gets selected correctly.
Score anchors
- 5
- specific verb+resource, distinguishes the tool from siblings
- 4
- clear but no sibling differentiation
- 3
- vague purpose
- 2
- tautology (restates name/title)
- 1
- missing or misleading
How to score well
- State what the tool does in one specific sentence: verb + resource + scope.
- If sibling tools could be confused with this one, say how it differs and name them.
- Never restate the name: a description that equals the tool name is capped at 2 and flagged.
See also
The normative text is the specification; this page restates it. All dimensions: dimensions.