1"""
2Tool Description Engineering -- Generation and Evaluation Utilities.
3 
4Use when: building, auditing, or iterating on tool descriptions for agent
5systems.  Provides templates for structured descriptions, a scoring evaluator
6that flags vague or incomplete descriptions, error-message generators that
7produce agent-recoverable responses, and a builder that assembles complete
8tool schemas.
9 
10Typical workflow:
11    1. Define a tool spec with ``ToolSchemaBuilder``.
12    2. Generate a rendered description with ``generate_tool_description``.
13    3. Score the description with ``ToolDescriptionEvaluator.evaluate``.
14    4. Generate error templates with ``ErrorMessageGenerator.generate``.
15 
16Example::
17 
18    builder = ToolSchemaBuilder("get_customer")
19    builder.set_description("Retrieve customer record", "Full details...")
20    builder.add_parameter("customer_id", "string", "CUST-######", required=True)
21    schema = builder.build()
22 
23    desc = generate_tool_description(schema)
24    scores = ToolDescriptionEvaluator().evaluate(desc, schema)
25"""
26 
27from __future__ import annotations
28 
29from dataclasses import dataclass, field
30from typing import Any, Dict, List, Optional, Protocol, Sequence
31import json
32import re
33 
34 
35__all__ = [
36    "generate_tool_description",
37    "generate_usage_context",
38    "ToolDescriptionEvaluator",
39    "ErrorMessageGenerator",
40    "ToolSchemaBuilder",
41]
42 
43 
44# ---------------------------------------------------------------------------
45# Protocols -- lightweight structural typing for tool specs
46# ---------------------------------------------------------------------------
47 
48class ToolSpec(Protocol):
49    """Structural interface expected by generation helpers.
50 
51    Use when: passing tool metadata objects that were not built with
52    ``ToolSchemaBuilder`` (e.g., third-party specs).
53    """
54 
55    name: str
56    description: str
57    triggers: Sequence[str]
58    examples: Sequence[Any]
59    parameters: Sequence[Dict[str, Any]]
60    returns: Dict[str, Any]
61    errors: Sequence[Dict[str, Any]]
62 
63 
64@dataclass
65class _BuiltToolSpec:
66    """Concrete implementation of ToolSpec returned by ToolSchemaBuilder.build()."""
67 
68    name: str
69    description: str
70    triggers: List[str]
71    examples: List[Dict[str, str]]
72    parameters: List[Dict[str, Any]]
73    returns: Dict[str, Any]
74    errors: List[Dict[str, Any]]
75 
76 
77# ---------------------------------------------------------------------------
78# Description Templates
79# ---------------------------------------------------------------------------
80 
81TOOL_DESCRIPTION_TEMPLATE: str = """
82## {tool_name}
83 
84{detailed_description}
85 
86### When to Use
87{usage_context}
88 
89### Parameters
90{parameters_description}
91 
92### Returns
93{returns_description}
94 
95### Errors
96{errors_description}
97"""
98 
99PARAM_TEMPLATE: str = """
100- **{param_name}** ({param_type}{required_label})
101 
102  {param_description}
103  {default_label}
104"""
105 
106 
107# ---------------------------------------------------------------------------
108# Generation helpers
109# ---------------------------------------------------------------------------
110 
111def generate_tool_description(tool_spec: ToolSpec) -> str:
112    """Render a complete markdown tool description from *tool_spec*.
113 
114    Use when: producing human-readable or agent-injectable documentation
115    from a structured spec object.
116    """
117    description: str = TOOL_DESCRIPTION_TEMPLATE.format(
118        tool_name=tool_spec.name,
119        detailed_description=tool_spec.description,
120        usage_context=generate_usage_context(tool_spec),
121        parameters_description=_generate_parameters(tool_spec.parameters),
122        returns_description=_generate_returns(tool_spec.returns),
123        errors_description=_generate_errors(tool_spec.errors),
124    )
125    return description
126 
127 
128def generate_usage_context(tool_spec: ToolSpec) -> str:
129    """Build the 'When to Use' section from triggers and examples.
130 
131    Use when: the caller needs only the usage-context fragment rather
132    than the full rendered description.
133    """
134    contexts: list[str] = []
135 
136    for trigger in tool_spec.triggers:
137        contexts.append(f"- When {trigger}")
138 
139    if tool_spec.examples:
140        contexts.append("\n**Examples**:\n")
141        for example in tool_spec.examples:
142            if isinstance(example, dict):
143                contexts.append(f"- Input: {example.get('input', '')}")
144                contexts.append(f"  Output: {example.get('tool_call', '')}")
145            else:
146                contexts.append(f"- {example}")
147 
148    return "\n".join(contexts)
149 
150 
151def _generate_parameters(parameters: Sequence[Dict[str, Any]]) -> str:
152    """Render parameter list to markdown."""
153    parts: list[str] = []
154    for p in parameters:
155        required_label = " | required" if p.get("required") else " | optional"
156        default = p.get("default")
157        default_label = f"Default: {default}" if default is not None else ""
158        parts.append(
159            f"- **{p['name']}** ({p['type']}{required_label})\n"
160            f"  {p['description']}\n"
161            f"  {default_label}".rstrip()
162        )
163    return "\n".join(parts)
164 
165 
166def _generate_returns(returns: Optional[Dict[str, Any]]) -> str:
167    """Render the returns section to markdown."""
168    if not returns:
169        return "No return value documented."
170    desc = returns.get("description", "")
171    rtype = returns.get("type", "object")
172    return f"{rtype} -- {desc}"
173 
174 
175def _generate_errors(errors: Sequence[Dict[str, Any]]) -> str:
176    """Render error definitions to markdown."""
177    if not errors:
178        return "No error conditions documented."
179    parts: list[str] = []
180    for err in errors:
181        parts.append(f"- **{err['code']}**: {err['description']} -- {err.get('resolution', '')}")
182    return "\n".join(parts)
183 
184 
185# ---------------------------------------------------------------------------
186# Evaluator
187# ---------------------------------------------------------------------------
188 
189class ToolDescriptionEvaluator:
190    """Score a rendered description against quality criteria.
191 
192    Use when: auditing existing tool descriptions for clarity,
193    completeness, accuracy, actionability, and consistency.
194    """
195 
196    CRITERIA: List[str] = [
197        "clarity",
198        "completeness",
199        "accuracy",
200        "actionability",
201        "consistency",
202    ]
203 
204    def evaluate(self, description: str, tool_spec: ToolSpec) -> Dict[str, float]:
205        """Return per-criterion scores (0.0 -- 1.0) for *description*.
206 
207        Use when: running automated quality checks on tool descriptions
208        before deploying them into an agent system.
209        """
210        results: Dict[str, float] = {
211            "clarity": self._check_clarity(description),
212            "completeness": self._check_completeness(description, tool_spec),
213            "accuracy": self._check_accuracy(description, tool_spec),
214            "actionability": self._check_actionability(description),
215            "consistency": self._check_consistency(description, tool_spec),
216        }
217        return results
218 
219    # -- private scoring helpers ------------------------------------------
220 
221    def _check_clarity(self, description: str) -> float:
222        """Score description clarity (0-1).
223 
224        Use when: detecting vague or ambiguous language that would
225        confuse an agent during tool selection.
226        """
227        vague_terms: list[str] = ["help", "assist", "thing", "stuff", "handle"]
228        vague_count: int = sum(1 for term in vague_terms if term in description.lower())
229 
230        ambiguous: list[str] = ["it", "this", "that"]
231        ambiguous_count: int = sum(1 for term in ambiguous if f" {term} " in description)
232 
233        clarity: float = 1.0 - (vague_count * 0.1) - (ambiguous_count * 0.05)
234        return max(0.0, clarity)
235 
236    def _check_completeness(self, description: str, tool_spec: ToolSpec) -> float:
237        """Score presence of required sections (0-1).
238 
239        Use when: verifying a description has all mandatory sections
240        before publishing.
241        """
242        required_patterns: list[tuple[str, str]] = [
243            ("description", r"## " + re.escape(str(getattr(tool_spec, "name", "")))),
244            ("parameters", r"### Parameters"),
245            ("returns", r"### Returns"),
246            ("errors", r"### Errors"),
247        ]
248        present: int = sum(
249            1 for _, pattern in required_patterns if re.search(pattern, description)
250        )
251        return present / len(required_patterns)
252 
253    def _check_accuracy(self, description: str, tool_spec: ToolSpec) -> float:
254        """Score alignment between description text and spec metadata.
255 
256        Use when: detecting description rot where the text no longer
257        matches the current tool spec.
258        """
259        score = 1.0
260        # Check that tool name appears in description
261        if hasattr(tool_spec, "name") and tool_spec.name not in description:
262            score -= 0.3
263        # Check parameter names appear
264        if hasattr(tool_spec, "parameters"):
265            for param in tool_spec.parameters:
266                pname = param.get("name", "") if isinstance(param, dict) else ""
267                if pname and pname not in description:
268                    score -= 0.15
269        return max(0.0, score)
270 
271    def _check_actionability(self, description: str) -> float:
272        """Score whether the description contains actionable cues.
273 
274        Use when: confirming agents can determine correct usage from
275        the description alone.
276        """
277        signals: list[str] = ["Use when", "Returns", "Errors", "Args", "Parameters"]
278        found: int = sum(1 for s in signals if s in description)
279        return min(1.0, found / max(1, len(signals)))
280 
281    def _check_consistency(self, description: str, tool_spec: ToolSpec) -> float:
282        """Score naming and formatting consistency.
283 
284        Use when: checking that parameter and section naming follows
285        conventions across the tool collection.
286        """
287        # Penalise mixed naming styles (camelCase vs snake_case)
288        camel = len(re.findall(r"[a-z][A-Z]", description))
289        snake = len(re.findall(r"[a-z]_[a-z]", description))
290        if camel > 0 and snake > 0:
291            return 0.5
292        return 1.0
293 
294 
295# ---------------------------------------------------------------------------
296# Error Message Generator
297# ---------------------------------------------------------------------------
298 
299class ErrorMessageGenerator:
300    """Produce structured, agent-recoverable error messages.
301 
302    Use when: building error responses that tell agents what went wrong,
303    why, and how to correct the call.
304    """
305 
306    TEMPLATES: Dict[str, str] = {
307        "NOT_FOUND": json.dumps({
308            "error": "{error_code}",
309            "message": "{specific_message}",
310            "resolution": "{how_to_resolve}",
311            "example": "{correct_format}",
312        }, indent=2),
313 
314        "INVALID_INPUT": json.dumps({
315            "error": "{error_code}",
316            "message": "Invalid {field}: {received_value}",
317            "expected_format": "{expected_format}",
318            "resolution": "Provide value matching {expected_format}",
319        }, indent=2),
320 
321        "RATE_LIMITED": json.dumps({
322            "error": "{error_code}",
323            "message": "Rate limit exceeded",
324            "retry_after": "{seconds}",
325            "resolution": "Wait {seconds} seconds before retrying",
326        }, indent=2),
327    }
328 
329    def generate(self, error_type: str, context: Dict[str, str]) -> str:
330        """Render an error message for *error_type* using *context* values.
331 
332        Use when: a tool needs to return a structured error that an agent
333        can parse and act on.
334        """
335        template: str = self.TEMPLATES.get(error_type, self.TEMPLATES["INVALID_INPUT"])
336        return template.format(**context)
337 
338 
339# ---------------------------------------------------------------------------
340# Schema Builder
341# ---------------------------------------------------------------------------
342 
343class ToolSchemaBuilder:
344    """Fluent builder for complete tool schemas.
345 
346    Use when: defining a new tool's schema programmatically and want
347    compile-time structure rather than hand-written dictionaries.
348    """
349 
350    def __init__(self, name: str) -> None:
351        self.name: str = name
352        self.description: str = ""
353        self.detailed_description: str = ""
354        self.parameters: List[Dict[str, Any]] = []
355        self.returns: Optional[Dict[str, Any]] = None
356        self.errors: List[Dict[str, str]] = []
357        self._triggers: List[str] = []
358        self._examples: List[Dict[str, str]] = []
359 
360    def set_description(self, short: str, detailed: str) -> "ToolSchemaBuilder":
361        """Set short and detailed description sections.
362 
363        Use when: providing both a one-line summary and a full
364        multi-paragraph description for the tool.
365        """
366        self.description = short
367        self.detailed_description = detailed
368        return self
369 
370    def add_parameter(
371        self,
372        name: str,
373        param_type: str,
374        description: str,
375        required: bool = False,
376        default: Optional[Any] = None,
377        enum: Optional[List[str]] = None,
378    ) -> "ToolSchemaBuilder":
379        """Append a parameter definition.
380 
381        Use when: declaring each accepted input for the tool.
382        """
383        self.parameters.append({
384            "name": name,
385            "type": param_type,
386            "description": description,
387            "required": required,
388            "default": default,
389            "enum": enum,
390        })
391        return self
392 
393    def set_returns(
394        self,
395        return_type: str,
396        description: str,
397        properties: Dict[str, Any],
398    ) -> "ToolSchemaBuilder":
399        """Define the return value schema.
400 
401        Use when: documenting what the tool sends back on success.
402        """
403        self.returns = {
404            "type": return_type,
405            "description": description,
406            "properties": properties,
407        }
408        return self
409 
410    def add_error(
411        self,
412        code: str,
413        description: str,
414        resolution: str,
415    ) -> "ToolSchemaBuilder":
416        """Register an error condition with recovery guidance.
417 
418        Use when: enumerating known failure modes so agents can
419        handle them gracefully.
420        """
421        self.errors.append({
422            "code": code,
423            "description": description,
424            "resolution": resolution,
425        })
426        return self
427 
428    def build(self) -> "_BuiltToolSpec":
429        """Assemble and return the complete tool spec.
430 
431        Use when: the builder is fully configured and the schema is
432        ready for registration, serialization, or passing to
433        ``generate_tool_description``.
434 
435        Returns a ``_BuiltToolSpec`` object that satisfies the ``ToolSpec``
436        protocol, so it can be used directly with ``generate_tool_description``
437        and ``ToolDescriptionEvaluator``.
438        """
439        return _BuiltToolSpec(
440            name=self.name,
441            description=self.detailed_description or self.description,
442            triggers=self._triggers,
443            examples=self._examples,
444            parameters=list(self.parameters),
445            returns=self.returns or {},
446            errors=list(self.errors),
447        )
448 
449    def add_trigger(self, trigger: str) -> "ToolSchemaBuilder":
450        """Add an activation trigger for the tool.
451 
452        Use when: documenting when agents should select this tool.
453        """
454        self._triggers.append(trigger)
455        return self
456 
457    def add_example(
458        self, input_text: str, tool_call: str
459    ) -> "ToolSchemaBuilder":
460        """Add a usage example.
461 
462        Use when: providing concrete input/output pairs that help agents
463        understand expected usage.
464        """
465        self._examples.append({"input": input_text, "tool_call": tool_call})
466        return self
467 
468 
469# ---------------------------------------------------------------------------
470# CLI entry point
471# ---------------------------------------------------------------------------
472 
473if __name__ == "__main__":
474    # Quick demo: build a schema, render it, and evaluate it.
475    builder = ToolSchemaBuilder("get_customer")
476    builder.set_description(
477        "Retrieve customer record by ID",
478        "Fetches a customer object from the primary datastore. "
479        "Supports concise and detailed response formats.",
480    )
481    builder.add_parameter(
482        "customer_id", "string",
483        'Customer identifier in CUST-###### format (e.g., "CUST-000001")',
484        required=True,
485    )
486    builder.add_parameter(
487        "format", "string",
488        '"concise" for key fields, "detailed" for complete record',
489        required=False,
490        default="concise",
491        enum=["concise", "detailed"],
492    )
493    builder.set_returns(
494        "object",
495        "Customer object with requested fields",
496        {"id": {"type": "string"}, "name": {"type": "string"}},
497    )
498    builder.add_error("NOT_FOUND", "Customer ID not in datastore", "Verify ID format and retry")
499    builder.add_error("INVALID_FORMAT", "ID does not match CUST-######", "Use CUST-###### pattern")
500 
501    spec = builder.build()
502 
503    print("=== Built Spec ===")
504    print(f"Name: {spec.name}")
505    print(f"Parameters: {[p['name'] for p in spec.parameters]}")
506    print(f"Errors: {[e['code'] for e in spec.errors]}")
507 
508    # Generate and evaluate description
509    description = generate_tool_description(spec)
510    print("\n=== Generated Description ===")
511    print(description)
512 
513    evaluator = ToolDescriptionEvaluator()
514    scores = evaluator.evaluate(description, spec)
515    print("\n=== Evaluation Scores ===")
516    for criterion, score in scores.items():
517        print(f"  {criterion}: {score:.2f}")
518 
519    # Generate an error message example
520    err_gen = ErrorMessageGenerator()
521    err_msg = err_gen.generate("NOT_FOUND", {
522        "error_code": "NOT_FOUND",
523        "specific_message": "No customer with ID CUST-999999",
524        "how_to_resolve": "Check ID and retry",
525        "correct_format": "CUST-######",
526    })
527    print("\n=== Sample Error Message ===")
528    print(err_msg)
529