PipelineHealer defines 6 GitHub workflow-related tools with acceptable naming consistency (all start with action verbs: get_, list_) and reasonably complete schemas. However, descriptions are generic and lack LLM-optimized context about WHEN to use each tool vs. alternatives. All 6 tools have input schemas with proper types and parameter descriptions, which is a strong foundation. Parameter descriptions are present but brief (mostly 20-50 chars). Error handling and output schemas are not visible in the provided code. The tools follow a read-only pattern (no state-modifying operations), which reduces some concerns, but descriptions do not articulate what makes each tool distinct or when the LLM should prefer one over another. Naming convention is solid (verb_noun pattern), but composition and schema documentation could be stronger.

• Expand tool descriptions to 100 - 200 characters each. Include context: WHAT it fetches, WHEN to call it (vs similar tools), and a sample of what the response structure looks like. Example: 'Get details of a workflow run including status, conclusion, head_commit, and run_number. Call this after list_repo_workflows to inspect a specific run. Returns full run metadata for context correlation.'
• Document output schemas explicitly in each tool definition. Specify all returned fields, types, and their purpose. This allows LLMs to know what chaining IDs and metadata are available for downstream calls.
• Add disambiguation text to tool descriptions. For example, get_job_logs differs from get_workflow_jobs in that it retrieves raw log text rather than job metadata. Make this clear: 'Get raw log text (plaintext) for a specific job. Use this after get_workflow_jobs to retrieve logs for a particular job. For job metadata and status, use get_workflow_jobs instead.'
• For list_repo_workflows and get_recent_commits, document the default and max limit for per_page. State whether results are truncated if they exceed the limit, and provide guidance on pagination (offset mechanism, total count returned, or cursor-based pagination).
• Implement and document error handling. Return structured errors with: (1) error category (e.g., 'not_found', 'rate_limit', 'permission_denied'), (2) a human-readable message, (3) recovery guidance (e.g., 'Retry after 60 seconds' for rate limits, or 'Check if the repository is public' for permission errors).

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry