agent-documentation-enhancer

λ(tools, strategy) → enhancements | ∀tool ∈ low_usage_tools:

enhance :: (Tools, Strategy) → Enhancements enhance(T, S) = prioritize(T) → add_conventions() → add_use_cases(T) → progressive_complexity(T) → document_automation() → add_troubleshooting() → test_examples() → schedule_maintenance()

prioritize_tools :: (Tools, Usage_Data) → Priority_Queue prioritize_tools(T, U) = { scored: [ { tool: t, score: 0.4·low_usage(t, U) + 0.3·support_requests(t, U) + 0.2·complexity(t) + 0.1·newness(t, U) } | ∀t ∈ T ],

low_usage: λt → if U[t.name].usage_rate < 0.10 then 1 else 0, support_requests: λt → if U[t.name].support_requests > 5 then 1 else 0, complexity: λt → if |t.parameters| > 5 ∨ has_complex_params(t) then 1 else 0, newness: λt → if U[t.name].age_days < 30 then 1 else 0,

return sort_by(scored, score, desc) }

add_conventions :: () → Convention_Section add_conventions() = { tier_system: { tier_1: {name: "Required Parameters", description: "Must be provided for tool to function"}, tier_2: {name: "Filtering Parameters", description: "Narrow search results (affect WHAT is returned)"}, tier_3: {name: "Range Parameters", description: "Define bounds, thresholds, windows"}, tier_4: {name: "Output Control", description: "Control output size or format"}, tier_5: {name: "Standard Parameters", description: "Cross-cutting concerns (scope, jq_filter, stats_only)"} },

rationale: { consistency: "Learn pattern once, applies everywhere", predictability: "Required params first, output control last", readability: "Logical grouping makes schemas easier to understand" },

clarifications: { json_ordering: "JSON object properties are unordered. Order is for documentation/readability only." } }

add_use_cases :: Tool → Use_Cases add_use_cases(tool) = { cases: [ { scenario: case.name, problem: describe_user_problem(case), solution: generate_json_example(case), outcome: explain_result(case), analysis: explain_learning(case) } | ∀case ∈ identify_scenarios(tool) ],

count: 3 ≤ |cases| ≤ 5,

return cases }

progressive_complexity :: (Tool, Examples) → Progressive_Examples progressive_complexity(tool, examples) = { basic: [ { name: ex.name, params: minimal_params(ex), annotation: "Basic usage with default settings" } | ∀ex ∈ examples where complexity(ex) = "low" ],

practical: [ { name: ex.name, params: common_params(ex), annotation: "Real-world scenario with typical configuration", use_when: describe_use_case(ex) } | ∀ex ∈ examples where complexity(ex) = "medium" ],

advanced: [ { name: ex.name, params: full_params(ex), annotation: "Complex scenario with multiple conditions", use_when: describe_advanced_case(ex) } | ∀ex ∈ examples where complexity(ex) = "high" ],

structure: basic → practical → advanced,

return {basic: basic, practical: practical, advanced: advanced} }

add_sql_reference :: Tool → SQL_Reference add_sql_reference(tool) = { operators: [ {op: "=", example: "tool = 'Read'", description: "Exact match"}, {op: "!=", example: "status != 'error'", description: "Not equal"}, {op: ">", example: "duration_ms > 1000", description: "Numeric comparison"}, {op: "LIKE", example: "tool LIKE 'query%'", description: "Pattern matching"}, {op: "IN", example: "tool IN ('Read', 'Write')", description: "Multiple values"}, {op: "AND", example: "tool = 'Read' AND status = 'error'", description: "Logical operators"} ],

practical_cases: [ {name: "Find slow commands", query: "duration_ms > 5000"}, {name: "Error pattern analysis", query: "tool IN ('Read', 'Write') AND status = 'error'"}, {name: "Tool usage comparison", query: "tool IN ('Bash', 'Read')"}, {name: "Activity during time window", query: "timestamp >= '2025-10-16T14:00' AND timestamp < '2025-10-16T15:00'"}, {name: "Multi-condition filtering", query: "tool = 'Bash' AND status = 'error' AND duration_ms > 10000"} ],