docs: add scheduling transactions details and examples in Hedera tools guide (#169)

Signed-off-by: skurzyp-blockydevs <stanislaw.kurzyp@blockydevs.com>

Author: skurzyp-blockydevs

docs/HEDERAPLUGINS.md

@@ -251,3 +251,75 @@ The Python SDK currently supports one agent mode:
 
 > **Coming Soon:** `AgentMode.RETURN_BYTES` - In this mode, the agent creates the transaction and returns the bytes for
 > the user to execute in another tool (human-in-the-loop pattern).
+
+---
+
+## Scheduling Transactions
+
+Most tools in the Hedera Agent Kit support **scheduled transactions**. This allows you to create a transaction that will be executed at a later time or once specific signatures are collected.
+
+### Scheduling Parameters
+
+When a tool supports scheduling, it accepts an optional `schedulingParams` object with the following fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `is_scheduled` | `boolean` | Set to `true` to create a scheduled transaction instead of executing immediately. |
+| `expiration_time` | `string` | ISO 8601 formatted date string (e.g., "2026-02-01T00:00:00Z") when the transaction expires if not fully signed. |
+| `wait_for_expiry` | `boolean` | If `true`, the transaction executes only at `expiration_time`. If `false` (default), it executes as soon as signatures are collected. |
+| `admin_key` | `boolean \| string` | Admin key to manage the scheduled transaction. `true` uses the operator key. |
+| `payer_account_id` | `string` | Account ID that pays the execution fee. Defaults to the operator. |
+
+### Supported Tools
+
+The following tools currently support transaction scheduling:
+
+**Core Account Plugin**
+*   `CREATE_ACCOUNT_TOOL`
+*   `UPDATE_ACCOUNT_TOOL`
+*   `TRANSFER_HBAR_TOOL`
+
+**Core Token Plugin**
+*   `CREATE_FUNGIBLE_TOKEN_TOOL`
+*   `CREATE_NON_FUNGIBLE_TOKEN_TOOL`
+*   `MINT_FUNGIBLE_TOKEN_TOOL`
+*   `MINT_NON_FUNGIBLE_TOKEN_TOOL`
+*   `TRANSFER_NON_FUNGIBLE_TOKEN_TOOL`
+*   `TRANSFER_NFT_WITH_ALLOWANCE_TOOL`
+*   `TRANSFER_FUNGIBLE_TOKEN_WITH_ALLOWANCE_TOOL`
+*   `AIRDROP_FUNGIBLE_TOKEN_TOOL`
+*   `DISSOCIATE_TOKEN_TOOL`
+*   `DELETE_NON_FUNGIBLE_TOKEN_ALLOWANCE_TOOL`
+
+**Core Consensus Plugin**
+*   `SUBMIT_TOPIC_MESSAGE_TOOL`
+
+**Core EVM Plugin**
+*   `CREATE_ERC20_TOOL`
+*   `TRANSFER_ERC20_TOOL`
+*   `CREATE_ERC721_TOOL`
+*   `MINT_ERC721_TOOL`
+*   `TRANSFER_ERC721_TOOL`
+
+### Prompting Best Practices
+
+To successfully create a scheduled transaction via an AI agent, use clear and explicit prompts:
+
+1.  **Explicit Intent**: clearly state that you want to *schedule* the transaction.
+2.  **Specific Timestamps**: Use exact dates for expiration or execution time. Avoid relative terms like "tomorrow" or "in 2 days" if possible, or ensure the agent can resolve them to a specific date.
+
+**Good Examples:**
+*   "Transfer 10 HBAR to 0.0.12345 and schedule it to expire on 2025-12-31."
+*   "Create a scheduled transaction to mint 100 tokens of 0.0.56789, executing on 2026-01-01."
+
+**Bad Examples:**
+*   "Transfer 10 HBAR later." (Vague timing)
+*   "Schedule a transfer." (Missing expiration details might default unexpectedly)
+
+### Python SDK Implementation
+
+In the Python SDK, scheduling is handled via the `OptionalScheduledTransactionParams` schema in `hedera_agent_kit.shared.parameter_schemas.common_schema`. Tools inheriting from this schema automatically support the parameters listed above.
+
+To enable scheduling in a custom tool:
+1.  Inherit from `OptionalScheduledTransactionParams`.
+2.  In your tool's logic, use `HederaBuilder.maybe_wrap_in_schedule` to conditionally wrap the transaction.

docs/HEDERATOOLS.md

@@ -83,6 +83,7 @@ Transfer HBAR between accounts.
 Transfer 0.1 HBAR to 0.0.12345
 Transfer 0.05 HBAR to 0.0.12345 with memo "Payment for services"
 Can you move 0.05 HBARs to account with ID 0.0.12345?
+Transfer 1 HBAR to 0.0.12345 and schedule the transaction with expiration time 01.02.2026
 ```
 
 ---
@@ -106,6 +107,7 @@ Creates a new Hedera account.
 Create a new Hedera account
 Create a new account with 10 HBAR
 Create an account with memo "My primary account" and 5 HBAR initial balance
+Create a new account with 10 HBAR and schedule the transaction with expiration time 01.02.2026
 ```
 
 ---
@@ -129,6 +131,7 @@ Update an account's metadata.
 ```
 Update account 0.0.12345 to have max auto associations of 10
 Set my account memo to "Updated account"
+Set my account memo to "Scheduled Update" and schedule this with expiration time 01.02.2026
 ```
 
 ---
@@ -404,6 +407,7 @@ Submit a message to an HCS topic.
 ```
 Submit "Hello World" to topic 0.0.12345
 Post a message "Daily update" to topic 0.0.12345
+Submit "Scheduled Message" to topic 0.0.12345 and schedule with expiration time 01.02.2026
 ```
 
 ---
@@ -524,7 +528,7 @@ Create a fungible token on Hedera.
 ```
 Create a fungible token named MyToken with symbol MTK
 Create a fungible token GoldCoin with symbol GLD, initial supply 1000, decimals 2, finite supply with max supply 5000
-Create a fungible token named MyToken with symbol MTK. Schedule the transaction instead of executing it immediately.
+Create a fungible token named MyToken with symbol MTK. Schedule the transaction with expiration 01.02.2026.
 ```
 
 ---
@@ -548,6 +552,7 @@ Create a non-fungible token (NFT) on Hedera.
 ```
 Create an NFT collection named MyNFT with symbol MNFT
 Create an NFT named ArtCollection with symbol ART and max supply 1000
+Create an NFT collection named ScheduledNFT and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -568,6 +573,7 @@ Mint additional supply of a fungible token.
 ```
 Mint 100 tokens of 0.0.12345
 Add 500 supply to token 0.0.12345
+Mint 100 tokens of 0.0.12345 and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -588,6 +594,7 @@ Mint NFTs with metadata.
 ```
 Mint NFT 0.0.12345 with metadata ipfs://QmTest123
 Mint 3 NFTs for token 0.0.12345 with URIs ["ipfs://a", "ipfs://b", "ipfs://c"]
+Mint NFT 0.0.12345 with metadata ipfs://Scheduled and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -608,6 +615,7 @@ Associate tokens with an account.
 ```
 Associate token 0.0.12345 with my account
 Associate tokens 0.0.12345 and 0.0.67890 with account 0.0.11111
+Associate token 0.0.12345 with my account and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -629,6 +637,7 @@ Dissociate tokens from an account.
 ```
 Dissociate token 0.0.12345 from my account
 Remove token 0.0.12345 association from account 0.0.67890
+Dissociate token 0.0.12345 from my account and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -651,6 +660,7 @@ Airdrop fungible tokens to multiple recipients.
 ```
 Airdrop 100 tokens of 0.0.12345 to accounts 0.0.11111 and 0.0.22222
 Send 50 tokens each of 0.0.12345 to three accounts
+Airdrop 100 tokens of 0.0.12345 to 0.0.11111 and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -673,6 +683,7 @@ Transfer fungible tokens using an allowance.
 ```
 Transfer 50 tokens of 0.0.12345 from 0.0.11111 to 0.0.22222 using allowance
 Use my token allowance to send 100 tokens from 0.0.11111
+Transfer 50 tokens of 0.0.12345 from 0.0.11111 using allowance and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -695,6 +706,7 @@ Transfer NFTs using an allowance.
 ```
 Transfer NFT 0.0.12345 serial 1 from 0.0.11111 to 0.0.22222 using allowance
 Use allowance to send NFT serial 5 from owner 0.0.11111
+Transfer NFT 0.0.12345 serial 1 from 0.0.11111 using allowance and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -717,6 +729,7 @@ Delete fungible token allowances.
 ```
 Delete token allowance for token 0.0.12345 from spender 0.0.67890
 Remove all token allowances for spender 0.0.67890
+Delete token allowance for token 0.0.12345 from spender 0.0.67890 and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -740,6 +753,7 @@ token.
 ```
 Delete NFT allowance for token 0.0.12345 serials [1, 2]
 Remove NFT allowance for token 0.0.67890 serial 5
+Delete NFT allowance for token 0.0.12345 serials [1] and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -763,6 +777,7 @@ a single transaction.
 ```
 Transfer NFT 0.0.12345 serial 1 to 0.0.67890
 Send NFT 0.0.12345 serial 2 from 0.0.11111 to 0.0.22222
+Transfer NFT 0.0.12345 serial 1 to 0.0.67890 and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -827,7 +842,7 @@ Deploy an ERC-20 token via factory contract.
 ```
 Create an ERC20 token named MyERC20 with symbol M20
 Create an ERC20 token GoldToken with symbol GLD, decimals 2, initial supply 1000
-Create an ERC20 token named "MyToken" with symbol MTK. Schedule this transaction instead of executing it immediately.
+Create an ERC20 token named "MyToken" with symbol MTK. Schedule with expiration 01.02.2026.
 ```
 
 ---
@@ -853,6 +868,7 @@ Transfer ERC-20 tokens.
 ```
 Transfer 100 tokens of contract 0.0.12345 to 0.0.67890
 Send 50 ERC20 tokens from 0x1234... to 0x5678...
+Transfer 100 tokens of 0.0.12345 to 0.0.67890 and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -874,6 +890,7 @@ Deploy an ERC-721 (NFT) token via factory contract.
 ```
 Create an ERC721 token named MyNFT with symbol MNFT
 Create an ERC721 collection called ArtDrops with symbol AD and base URI ipfs://Qm...
+Create an ERC721 token named MyNFT with symbol MNFT and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -895,6 +912,7 @@ Mint a new ERC-721 NFT by calling the `safeMint(to)` function on the contract.
 Mint ERC721 token 0.0.6486793 to 0xd94dc7f82f103757f715514e4a37186be6e4580b
 Mint ERC721 token 0.0.6486793 to Hedera account ID 0.0.2222222
 Mint ERC721 token 0.0.9999
+Mint ERC721 token 0.0.9999 and schedule with expiration 01.02.2026
 ```
 
 ---
@@ -921,6 +939,7 @@ Transfer an ERC-721 NFT.
 ```
 Transfer ERC721 token 0 from contract 0.0.12345 to 0.0.67890
 Send NFT #5 from 0x1234... to 0x5678...
+Transfer ERC721 token 0 from contract 0.0.12345 to 0.0.67890 and schedule with expiration 01.02.2026
 ```
 
 ---