> ## 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.

# Make your first tool request

> Describe a Plyne tool, validate its input and credit quote, execute a company lookup, and retrieve the same operation through the API or MCP.

Use `company_profile` to retrieve a company profile from a LinkedIn company URL. This walkthrough uses the public Plyne company URL as an input example; the returned fields depend on the eligible source and available data.

## 1. Set your API key

Create a workspace API key in **Developer → API Keys** in the portal. Keep the key in your application environment rather than in client-side code.

```bash theme={null}
export PLYNE_API_URL='https://api.plyne.ai'
export PLYNE_API_KEY='REPLACE_WITH_YOUR_WORKSPACE_KEY'
```

## 2. Read the tool contract

Describe the tool before constructing a request. The descriptor includes accepted input fields, source options, output fields and billing guidance.

```bash theme={null}
curl "$PLYNE_API_URL/v1/tools/company_profile" \
  -H "Authorization: Bearer $PLYNE_API_KEY"
```

The [company profile reference](https://docs.plyne.ai/tools/enrich-company.md) documents the same contract. Other tools can require different identities, filters or result limits.

## 3. Check the plan

Planning validates the input and returns source eligibility and the maximum credit quote. It makes no acquisition request and reserves no credits.

```bash theme={null}
curl "$PLYNE_API_URL/v1/tools/company_profile/plan" \
  -H "Authorization: Bearer $PLYNE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"linkedin_url":"https://www.linkedin.com/company/plyne-ai"}'
```

Check the returned `providers` and `pricing`. A plan does not guarantee that a source will remain available or return data when execution starts.

## 4. Execute once

Choose a new `Idempotency-Key` for this operation. The example key below is illustrative; replace it for each new operation.

```bash theme={null}
curl "$PLYNE_API_URL/v1/tools/company_profile/execute" \
  -H "Authorization: Bearer $PLYNE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: company-profile-first-001' \
  --data '{"linkedin_url":"https://www.linkedin.com/company/plyne-ai"}'
```

Inspect `status`, `data`, `sources` and `usage`. Single-company lookups omit pagination. A `not_found` response is possible; company enrichment has its own billing policy, so do not assume every empty lookup is free.

## 5. Retrieve the same operation

Repeat the original body and key to retrieve the operation. A completed replay returns the saved result without another acquisition charge. If the connection fails or the response is incomplete, retrieve the same operation before creating a new key.

## Use the same tool through MCP

Connect to `/mcp` with OAuth or your workspace API key. First call `plan_tool` with the proposed input:

```json theme={null}
{
  "name": "plan_tool",
  "arguments": {
    "tool": "company_profile",
    "input": {"linkedin_url": "https://www.linkedin.com/company/plyne-ai"}
  }
}
```

Check the eligible sources and credit reservation. Then execute using these `tools/call` parameters, with the request key inside `arguments`:

```json theme={null}
{
  "name": "company_profile",
  "arguments": {
    "linkedin_url": "https://www.linkedin.com/company/plyne-ai",
    "idempotency_key": "company-profile-first-001"
  }
}
```

When used in the same workspace with the same request and key, API and MCP refer to the same operation. See [acquisition MCP](https://docs.plyne.ai/mcp/acquisition-tools.md) for connection details.

> [card] [Choose a chain](https://docs.plyne.ai/guides/source-chains.md)
>
> Control source order and fallback conditions.

> [card] [Understand credits](https://docs.plyne.ai/guides/credits-and-recovery.md)
>
> Understand reservation, settlement and interrupted requests.


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