The Discovery Protocol

The Discovery Cycle

Every Elemm session follows a strict, five-stage handshake. The gateway enforces this order — any action attempted before the handshake completes is rejected with a PROTOCOL_VIOLATION error.

Phase 1: Connect

connect_to_site(url="https://api.example.com/openapi.json")

The agent connects to a remote API. The gateway auto-detects the interface type:

1. Probes for a native Elemm manifest at url/.well-known/elemm-manifest.md
2. Tests if it's a GraphQL endpoint (via query { __typename })
3. Checks for a valid OpenAPI specification (JSON/YAML)
4. Scans standard paths (/graphql, /openapi.json, /swagger.json, /api-docs)

Phase 2: Get Manifest (Handshake)

get_manifest()

Returns the system instructions, protocol rules, and landmark topology. This call authorizes the session — it completes the handshake.

Phase 3: Discover

get_landmarks()

Returns a summary of available functional areas. Landmarks blocked by the Security Policy are automatically hidden.

Example output:

### LANDMARK TOPOLOGY
- **repos**: (15 tools)
- **issues**: (8 tools)
- **git**: (12 tools)

Phase 4: Inspect

inspect_landmark(landmark_id="repos")

Returns full TypeScript-style signatures for all tools within the specified landmark(s). This is the ground truth for parameter schemas.

Example output:

/**
 * Tool: repos_repos_get
 * @param owner (string) [REQUIRED] The account owner
 * @param repo (string) [REQUIRED] The repository name
 */
function call_action(action: 'repos_repos_get', parameters: { owner: string, repo: string }): any;

Phase 5: Execute

call_action(action="repos_repos_get", parameters={"owner": "v3rm1ll1on", "repo": "elemm"})

Only after inspection does the agent execute actions — either individually via call_action() or as a pipeline via execute_sequence().

Handshake Enforcement

• On every connect_to_site call, the internal manifest_loaded flag is reset to false.
• The flag is set to true when either get_manifest() or get_landmarks() is called.
• Any call to call_action, execute_sequence, or direct actions before the handshake returns:

{
  "status": "error",
  "_PROTOCOL_ERROR": "PROTOCOL_VIOLATION",
  "message": "Protocol violation: You MUST call 'get_manifest' before executing any actions.",
  "remedy": "Call 'get_manifest' immediately to authorize the session."
}

Fast Alternative: search_landmarks

When the agent already knows the approximate tool name, it can skip hierarchy navigation entirely:

search_landmarks(query="repos|issues")

search_landmarks is a global regex search over all landmarks and actions. It returns executable actions directly — ideal when the tool name is partially known.

Context Protection for Large Environments

To protect the agent's context in very large environments (100k+ tools):

• Default Cap: Broad search results are automatically limited to 10 entries.
• Truncation Warning: When there are more results, a warning with the total count is injected.
• Dynamic Recommendation: The response recommends narrowing the search, e.g., via inspect_landmark(landmark_id="Zentrum:Sector_042:energy").

Protocol Constraints

1. Handshake Requirement — get_manifest() must be called before any execution.
2. Broker Isolation — The gateway only exposes 9 core tools. Domain-specific tools are never leaked.
3. Parameter Filtering — The engine strictly filters tool arguments and only passes defined parameters to the underlying function.
4. Placeholder Rejection — Arguments containing unresolved placeholders ("UNKNOWN", "PLACEHOLDER", literal "$stepN") are rejected before execution.