fix: teach single_agent to use return_table + response_schema for lists (#5113)

## Summary

- Adds defense-in-depth guidance across all 4 layers the agent reads so
it knows to set `return_table=True` + `response_schema` when using
`single_agent` for list generation
- Without these params, lists get crammed into a single `{"answer":
string}` text blob instead of a structured multi-row table

### Files changed
1. **sdk_manager.py** (system prompt) — bolded instruction on the
single_agent bullet
2. **app.py** (MCP instructions) — appended list generation guidance
3. **tools.py** (tool docstring) — added "For list generation" paragraph
+ concrete example
4. **models.py** (field descriptions) — made `response_schema` and
`return_table` descriptions prescriptive

## Test plan

- [x] Agent unit tests pass (135/135)
- [x] MCP server tests pass (356/356)
- [ ] Manual: ask everyrow-cc "Find 15 AI startups in healthcare" —
verify it sets `return_table=True` and provides a schema
- [ ] Regression: single-value queries ("What is the capital of
France?") still work without return_table

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Sourced from commit 5a16b968f1b794df8a329e59f84f9c75db682070

Author: jackwildman

futuresearch-mcp/src/futuresearch_mcp/app.py

@@ -89,7 +89,9 @@ async def no_auth_http_lifespan(_server: FastMCP):
 2. **URLs** — upload from a URL or Google Sheet via `futuresearch_upload_data`.
 3. **From memory** — if you know a good starting list, generate it as inline `data`.
 4. **single_agent** — dispatch a research agent to find or build a list. \
-Works well but slow (3-5 min), so prefer the options above.
+Works well but slow (3-5 min), so prefer the options above. \
+When generating a list, always set `return_table=True` and provide a `response_schema` \
+defining the fields per item — otherwise results come back as a single text string.
 
 ## Choosing the right operation
 

futuresearch-mcp/src/futuresearch_mcp/models.py

@@ -556,7 +556,9 @@ class SingleAgentInput(BaseModel):
     )
     response_schema: dict[str, Any] | None = Field(
         default=None,
-        description="Optional JSON schema for the agent response.",
+        description="JSON schema for the agent response. Required when return_table=True "
+        "to define the fields for each item in the list. If omitted, results default to "
+        'a single {"answer": string} field.',
     )
     effort_level: EffortLevel | None = Field(
         default=EffortLevel.MEDIUM,
@@ -581,7 +583,9 @@ class SingleAgentInput(BaseModel):
     )
     return_table: bool = Field(
         default=False,
-        description="If true, return results as a multi-row table (one row per item). Use when the task produces a list of items (e.g. 'list all X'). If false (default), return a single result row.",
+        description="MUST be true when the task asks for a list of items (e.g. 'find 15 startups', "
+        "'list all X'). Always pair with response_schema to define the fields per item. "
+        "If false (default), returns a single result row.",
     )
     session_id: str | None = Field(
         default=None,

futuresearch-mcp/src/futuresearch_mcp/tools.py

@@ -336,10 +336,17 @@ async def futuresearch_single_agent(
     multi-field output. Do NOT describe desired output columns only in `task`
     — the schema is what controls the output structure.
 
+    **For list generation:** When the task asks for a list of items, set
+    `return_table=True` and provide a `response_schema` defining the fields
+    for each item. This returns a multi-row table instead of a single text blob.
+
     Examples:
     - "Find the current CEO of Apple and their background"
     - "Research the latest funding round for this company" (with input_data: {"company": "Stripe"})
     - "What are the pricing tiers for this product?" (with input_data: {"product": "Snowflake"})
+    - "Find 15 AI startups in healthcare" (with return_table=True and response_schema:
+      {"type": "object", "properties": {"name": {"type": "string"}, "description": {"type": "string"},
+       "url": {"type": "string"}}, "required": ["name", "description"]})
 
     This function submits the task and returns immediately with a task_id.