PROBLEM — Today, reaching an instance's own underlying tools (for example a coder instance's GitHub actions) requires two hops: list_instance_tools to discover the exact tool name and schema, then call_instance_tool to invoke it. This is the right shape when a caller genuinely does not know in advance what an instance exposes. But a growing class of callers already know exactly which instance and which agent type they are talking to for the entire lifetime of the connection — for example, a chat project pinned permanently to one coder instance. For that caller, the discovery hop adds latency and token cost on every single nested call, for zero actual benefit, since the tool set never changes within that session.
OBSERVED — In practice this repeatedly produced guessed tool names and guessed field names (for example, trying issue_number before discovering the real field is number on github_read_issue) before the discovery call was made correctly. The two-layer indirection makes the exact tool contract non-obvious without paying the discovery cost every time, and skipping that cost tends to produce guesses instead.
PROPOSAL — Expose a direct, first-class tool surface scoped per AGENT TYPE (not per instance), since instances of the same agent type expose the same underlying tool set. A caller already pinned to a known agent type could call that agent type's tools directly, with the specific instance id passed as a normal parameter, the same way it already is today inside call_instance_tool's input. This removes the discovery hop entirely for callers in that position, while leaving list_instance_tools and call_instance_tool in place for callers that legitimately need to discover an unfamiliar or dynamic tool set.
OPEN QUESTION FOR IMPLEMENTATION — Confirm whether tool sets genuinely are identical across all instances of the same agent type (for example, are all coder instances guaranteed the same GitHub/coding tool surface), or whether they can legitimately diverge per instance (different repo permissions, different connected services). If they can diverge, this proposal needs a fallback: direct exposure of whatever is common to the agent type, with call_instance_tool remaining the escape hatch for instance-specific extras.
RELATED — This is a separate concern from #757 (board-driven ticket queue). That issue is about work scheduling; this one is about the tool-calling contract shape itself.
PROBLEM — Today, reaching an instance's own underlying tools (for example a coder instance's GitHub actions) requires two hops: list_instance_tools to discover the exact tool name and schema, then call_instance_tool to invoke it. This is the right shape when a caller genuinely does not know in advance what an instance exposes. But a growing class of callers already know exactly which instance and which agent type they are talking to for the entire lifetime of the connection — for example, a chat project pinned permanently to one coder instance. For that caller, the discovery hop adds latency and token cost on every single nested call, for zero actual benefit, since the tool set never changes within that session.
OBSERVED — In practice this repeatedly produced guessed tool names and guessed field names (for example, trying issue_number before discovering the real field is number on github_read_issue) before the discovery call was made correctly. The two-layer indirection makes the exact tool contract non-obvious without paying the discovery cost every time, and skipping that cost tends to produce guesses instead.
PROPOSAL — Expose a direct, first-class tool surface scoped per AGENT TYPE (not per instance), since instances of the same agent type expose the same underlying tool set. A caller already pinned to a known agent type could call that agent type's tools directly, with the specific instance id passed as a normal parameter, the same way it already is today inside call_instance_tool's input. This removes the discovery hop entirely for callers in that position, while leaving list_instance_tools and call_instance_tool in place for callers that legitimately need to discover an unfamiliar or dynamic tool set.
OPEN QUESTION FOR IMPLEMENTATION — Confirm whether tool sets genuinely are identical across all instances of the same agent type (for example, are all coder instances guaranteed the same GitHub/coding tool surface), or whether they can legitimately diverge per instance (different repo permissions, different connected services). If they can diverge, this proposal needs a fallback: direct exposure of whatever is common to the agent type, with call_instance_tool remaining the escape hatch for instance-specific extras.
RELATED — This is a separate concern from #757 (board-driven ticket queue). That issue is about work scheduling; this one is about the tool-calling contract shape itself.