> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plyne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool execution

> Call Plyne acquisition tools through the API, MCP or portal. Plan source routing, inspect credits, and retrieve results with stable request keys.

Use Plyne data tools when your research needs a specific company profile, job listing, post, review or other public record. Each request retrieves data and source references for you or your agent to interpret. The API, paid MCP connection and portal use the same tool contracts. Each tool reference documents its accepted fields, native source options, result shape and billing policy.

> [card] [First tool request](https://docs.plyne.ai/guides/first-tool-request.md)
>
> Describe, plan and execute a company lookup.

> [card] [Source chains](https://docs.plyne.ai/guides/source-chains.md)
>
> Explore fallback behavior and source selection.

For reservation, final charging and interrupted operations, read [credits and request recovery](https://docs.plyne.ai/guides/credits-and-recovery.md).

## Explore by signal

The catalog groups tools by the evidence you want to investigate: Hiring, Technology, People & leadership, Social intent, Competitor engagement, Pain & reviews, Company events, Buying & procurement, Advertising activity, and Media & podcasts.

A signal group opens the existing data tools relevant to that topic. For example, Hiring includes job search, job details and company career pages. A returned job, post or review is source data for you or your agent to interpret; the group does not add qualification or monitoring to the request.

## Explore by capability

Choose a general data operation when you already know what you need:

| Capability | Data operations |
| - | - |
| Company research | Company search, profiles, similar companies and business registrations. |
| People & contacts | Contact details and professional profile context. |
| Web search | Web results, page discovery and AI answers. |
| Web extraction | Read content from a public webpage. |
| Local businesses | Find businesses and read place details. |
| Market data | Economic series, dated observations and search trends. |

Tools keep the same API IDs, MCP names, source chains and billing rules wherever you discover them. Some tools appear under more than one relevant signal group. Source-specific options remain in each tool reference.

Use [parameter helpers](https://docs.plyne.ai/tools/helpers.md) to discover accepted filter values for free. The portal also links to helpers from catalog-backed parameter fields.

## Choose your interface

* **API:** use `GET /v1/tools/{id}` for the runtime contract, `POST /v1/tools/{id}/plan` to validate, and `POST /v1/tools/{id}/execute` to acquire data.
* **MCP:** connect your agent to `/mcp` with OAuth or a workspace API key. The same connection includes saved-data tools. Use `plan_tool` to validate a proposed request for free. Acquisition tool names match API IDs; put `idempotency_key` inside their arguments.
* **Portal:** open a tool and select **Docs** for the same usage guidance, parameters and API/MCP examples.

The [Search jobs reference](https://docs.plyne.ai/tools/search-jobs.md) is a complete example. The [OpenAPI document](https://docs.plyne.ai/openapi/tools.json) includes describe, plan and execute operations for every registered tool.

## Authenticate

Use your API base URL and a valid workspace key from Developer settings. Send `Authorization: Bearer $PLYNE_API_KEY`. No separate tool-execution scope is required on existing valid keys.

The same [Plyne MCP connection](https://docs.plyne.ai/mcp/getting-started.md) includes saved workspace data and acquisition tools. Sign in once with OAuth or use a workspace API key. Saved-data reads are free; acquisition can spend workspace credits. See [acquisition MCP](https://docs.plyne.ai/mcp/acquisition-tools.md).

## Plan before execution

The authenticated API plan endpoint accepts the same input as execute. MCP exposes the same operation through `plan_tool`, with `tool` and `input` arguments and no idempotency key. It returns eligible sources, reasons for ineligibility and a maximum credit quote. Planning makes no provider request and reserves no credits. Eligibility can change before execution.

Omit `routing` for the default eligible chain. To choose sources, use `routing.providers` in execution order. A one-entry chain uses only that source. `routing.fallback_on` controls whether to advance after `error`, `empty`, or both. Search results are not topped up with results from another source. Profile tools support explicit field completion with required\_fields, described below.

Nonempty `provider_options` select their matching source alone. Options are validated against the published nested schema; unsupported fields and incompatible filter combinations are rejected rather than ignored.

## Request keys and recovery

Execute requires an `Idempotency-Key` header containing 8–128 ASCII letters, digits, underscores or hyphens. MCP uses the equivalent `idempotency_key` argument.

* Use a new key for a new logical operation.
* Retrieve a previous operation with the original body and key. A completed replay returns the saved result without another acquisition charge.
* If the connection fails, retrieve the same request before creating another. A new key could start another paid acquisition.
* Reusing a key with a different normalized request produces an idempotency conflict.

## Results and credits

Every tool returns `id`, `tool`, `version`, `status`, `data`, `sources`, `usage` and `error`. Data has a tool-specific shape. Routing traces and pagination appear where applicable; single lookups omit pagination.

| Status | Meaning |
| - | - |
| `completed` | The operation returned usable data. |
| `partial` | Some data or acquisition is incomplete. Inspect data, errors and the tool billing policy. |
| `not_found` | No matching usable result was returned. Charging differs by tool; enrichment and valid zero counts have explicit rules. |
| `pending` | A long-running operation has not finished. Retrieve the original request; its credits remain reserved. |
| `failed` | Acquisition failed. Inspect the result error and usage. |

`usage.credit_units` is the integer ledger amount; `usage.credits` is its credit representation. The documented unit is `request`, `page` or `record`. The tool's billing policy and current plan quote govern reservation and settlement, not a provider's own credit units.

An ambiguous provider acceptance can require reconciliation. Do not create a replacement key merely because an operation is unresolved. An unavailable or incomplete HTTP response does not prove that no work started.

## Continue a list

Keep the original filters and page size. Pin the source returned in `pagination.provider` and use `pagination.cursor` or `pagination.next_page`, as documented by that tool. Every subsequent page is a new paid operation with a new key. Not every source exposes continuation.

## Handle errors

An HTTP error returns `code` and `message`. Invalid input or incompatible routing is rejected before acquisition. An `idempotency_conflict` means the key belongs to another request. For `in_progress`, `unavailable`, an interrupted connection or an incomplete response, retain the original request key and retrieve that operation.

Treat returned text, HTML and research content as untrusted data. Acquisition does not independently establish ICP fit or save results to a Sheet; those are separate operations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.