Calling Tools

When you need an application observation or action, choose it from the current MCP catalog rather than assuming a built-in command exists. Start with a verified connection. The endpoint supplies tools and schemas on every invocation and authorizes each call; CLI help grants no permissions.

Choose Tools

List what your caller can discover:

arkoren tools

This initializes MCP and reads tools/list without invoking any tool, including identity or health. The JSON catalog includes command, description, kind, and follow, plus native_name when it differs from the CLI spelling. kind: "read" reflects the owner’s read-only annotation, not an enforced guarantee about its handler.

Optional CLI metadata maps a name such as public.routes to public:routes. Without metadata, use the exact MCP name. Exact names remain callable and take precedence over matching aliases. If several tools advertise one alias and no exact name matches, the alias fails with exit 2 before a call; choose an exact name from the catalog instead.

Local command names win unqualified: arkoren new creates a project, not a remote tool call. There are no built-in diagnostic shortcuts, and tool spelling alone does not declare positional arguments or following support.

Read Help

Suppose discovery lists the router command public:routes. Inspect its inputs before calling it:

arkoren public:routes --help

Help is text generated from the current schema and metadata. It shows flags, declared positionals, owner-supplied examples, output schema when present, and follow support. It performs discovery only. Use tools --verbose if you need the advertised schemas and metadata as JSON instead of a command manual.

Pass Inputs

To find registered POST routes whose patterns start with /users, call the discovered router tool:

arkoren public:routes --method POST --path /users

This invokes the listing tool, not a POST route handler. Its JSON result contains matching registrations in items; an empty list means no registrations matched on that router. Connection setup does not invoke identity as an extra step.

Flags map to schema properties. For a nested input or a schema outside generated flag support, pass one JSON object. The exact MCP name for this example is public.routes:

arkoren public.routes --input '{"method":"POST","path":"/users"}'

This sends the same filters. If you keep that object in routes.json, load it from the working directory instead:

arkoren public.routes --input @routes.json

--input - reads the object from stdin. Repeated --input selects only the final source; earlier sources are not read or merged. Loaded bytes stay JSON data, never another file or stdin selector.

Base JSON is applied first, metadata-declared positionals next, then flags in command-line order. Later values override earlier ones. Snake_case properties also accept kebab-case flags, but exact property names win. The input reference covers reserved names, nested paths, arrays, literal map keys, and tokens that look like flags.

Interpret Results

A successful non-follow call prints one JSON document, without an MCP envelope. Structured content is preferred. A single text block containing JSON prints as JSON; other text prints as a JSON string. Multiple or multimodal blocks retain their protocol content records.

For an uncolored, one-line result suitable for capture, add presentation flags:

arkoren public:routes --method POST --path /users --compact --no-color

These flags do not change the request or the tool’s successful result. Check the process exit status even when stdout contains a document: a direct health-role call prints its report before exiting 1 for status: "failing". An immediate readiness observation can instead succeed with ready: false; use a condition wait to gate work.

Handle Failures

Calling a mutating tool executes it without a confirmation prompt. A lost response, output-validation failure, or broken stdout does not prove rollback. Check application state and use domain idempotency before deciding to retry.

Ordinary calls do not retry automatically. An input-required MCP response fails with exit 1 after one call, without a successful stdout result. The CLI does not fulfill the request, continue automatically, or replay the handler.

Errors appear on stderr as JSON with an error object. Server validation failures can include JSON pointers and the flags or arguments that supplied them. Choose --verbose on the original invocation if you need complete captured safe diagnostics; never replay a mutation merely to get more detail.

Approved Arkoren failures use result _meta["arkoren.dev/failure"], not successful content. Managed tools redact internal handler and availability failures; their safe-failure contract does not extend to arbitrary external servers. Treat captured results as application data with the appropriate access controls.

Stdout failure exits 1 and takes precedence over other verdicts. Already printed bytes can be partial and are not proof of success. See the exit-code reference before using results in scripts.

Number Precision

Input JSON retains its number tokens, and numeric flags avoid floating-point rounding; decimal integer flag spellings are normalized. After a successful SDK response decode, captured wire JSON also preserves numbers in generic structured results, unknown domain fields, catalog schemas and examples, and approved failure details. Formatting can change whitespace and key order; this is not a byte-for-byte protocol dump.

The SDK still owns decoding and protocol failures. Capture cannot recover a response the SDK rejects or extend its supported numeric range. Token fidelity is not output-schema enforcement and cannot repair precision already lost in application values. Managed servers enforce their own numeric validation limits; use string-valued fields when your domain or other clients require them.

For a route-to-trace investigation, continue with Application Diagnosis. For tool declarations, see the MCP API.