feat: add external job tools + improve LLM-facing tool descriptions

Add 3 new MCP tools for inspecting YARN applications NOT submitted
through this service: get_external_job_logs, get_external_job_status,
get_external_job_result. Each takes application_id + connection_name
and queries YARN directly, bypassing the local JobStore.

- spark_executor/tools/external_jobs.py: 3 tool functions
- spark_executor/tools/requests.py: 3 new Pydantic body models
  (ExternalJobLogsRequest, ExternalJobStatusRequest,
  ExternalJobResultRequest)
- spark_executor/server.py: 3 new POST routes with explicit operation_id
- tests/unit/test_external_jobs.py: 7 unit tests
- tests/integration/test_mcp_routes.py: assert 20 tool routes
- README.md: list the 3 new tools

To make the LLM pick the right tool and not guess at field values,
also:

- Add Pydantic field descriptions for 22 fields across 8 request models
  (SaveConnectionRequest, UpdatePendingJobRequest, GetJobLogsRequest,
  JobIdRequest, PendingIdRequest, ConnectionNameRequest, plus the new
  ExternalJob*Request models).
- Update 12 route descriptions with cross-references, prerequisite
  context, and 400 behavior notes.
- Refactor _unknown_job_error: an input that looks like a YARN
  application_id (starts with 'application_') now returns HTTP 400
  (ValueError) with a hint message naming the right external tool;
  other not-found cases still return 404 (KeyError). This catches the
  common LLM mistake of passing application_id to the internal
  get_job_* / kill_job tools.
- 4 new unit tests for the 400 behavior.

Tests: 356 passed (up from 242).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

spark_executor/tools/logs.py

@@ -11,14 +11,31 @@ from spark_executor.tools.connections import store as conn_store
 store = JobStore()
 
 
-def _unknown_job_error(uid: str) -> KeyError:
-    """Standard "we tried both IDs and found nothing" message.
+def _unknown_job_error(uid: str, external_tool_hint: str | None = None) -> Exception:
+    """Build the right error for a not-found job.
 
     The agent gets this from confirm_submit_job's response:
         {"job_id": "a1b2c3d4e5f6", "application_id": "application_...", ...}
-    and routinely confuses which to pass here. Spelling out that BOTH
-    IDs were tried (and what they look like) saves a round trip.
+    and routinely confuses which to pass here. We differentiate two cases:
+
+    - `uid` looks like a YARN application_id (starts with 'application_')
+      AND the caller passed an `external_tool_hint`: the YARN app likely
+      exists, this tool just can't serve it because it was not submitted
+      through this service. Raise ValueError (-> 400 via the FastAPI
+      handler) pointing the agent at the right external tool.
+    - Otherwise: no local record of either form of id. Raise KeyError
+      (-> 404). Spelling out what both IDs look like saves a round trip.
     """
+    if uid.startswith("application_") and external_tool_hint:
+        return ValueError(
+            f"job_id={uid!r} looks like a YARN application_id (starts with "
+            f"'application_'), but this tool only works for jobs submitted "
+            f"through this MCP service (no local JobStore record). For YARN "
+            f"applications not submitted here, use {external_tool_hint} "
+            f"instead. (If you actually submitted this job through this "
+            f"service, pass the local job_id — it is a 12-char hex like "
+            f"'a1b2c3d4e5f6'.)"
+        )
     return KeyError(
         f"No Job found for id={uid!r} (neither as job_id nor as "
         f"application_id). Pass the job_id from confirm_submit_job's "
@@ -37,7 +54,10 @@ def get_job_logs(job_id: str, tail_chars: int = 5000) -> str:
     logger.debug(f"get_job_logs enter job_id={job_id} tail_chars={tail_chars}")
     job = store.get_either(job_id)
     if job is None:
-        raise _unknown_job_error(job_id)
+        raise _unknown_job_error(
+            job_id,
+            external_tool_hint="get_external_job_logs(application_id, connection_name, tail_chars)",
+        )
     conn = conn_store.get(job.connection)
     if conn is None:
         raise KeyError(f"Connection not found: {job.connection}")