chore: improve docs

2 files changed, 59 insertions, 24 deletions

diff --git a/docs/agent.md b/docs/agent.md
index 802108d..c74d2f3 100644
--- a/docs/agent.md
+++ b/docs/agent.md
@@ -50,6 +50,7 @@ variables:
     description: This is a bar with default value
     default: val
 ```
+> For sensitive information such as api_key, client_id, client_secret, and token, it's recommended to use environment variables instead of agent variables.
 
 When use define variables, please avoid these built-in variables:
 
@@ -90,7 +91,8 @@ documents:
 
 ### conversation_starters
 
-Predefined prompts or questions that the agent can use to initiate interactions or conversations.
+Define Predefined prompts or questions that users can ask to initiate interactions or conversations with the agent.
+This helps provide guidance for users on how to engage with the agent effectively.
 
  ```yaml
  conversation_starters:
diff --git a/docs/tool.md b/docs/tool.md
index 18fce65..2d4c866 100644
--- a/docs/tool.md
+++ b/docs/tool.md
@@ -261,35 +261,68 @@ def git_diff(target: str):
 
 ## Quickly Create Tools
 
-`Argcfile.sh` provides a tool to quickly create script tools.
+### Use argc
 
+`Argcfile.sh` provides a tool `create@tool` to quickly create tool scripts.
+
+```sh
+argc create@tool _test.sh foo bar! baz+ qux*
 ```
-$ argc create@tool -h
-Create a boilplate tool script
 
-Examples:
-  ./scripts/create-tool.sh _test.py foo bar! baz+ qux*
+The argument details
 
-USAGE: create-tool [OPTIONS] <NAME> [PARAMS]...
+- `_test.sh`: The name of the tool script you want to create. The file extension can only be `.sh`, `.js`, or `.py`.
+- `foo bar! baz+ qux*`: The parameters for the tool.
 
-ARGS:
-  <NAME>       The script file name.
-  [PARAMS]...  The script parameters
+The suffixes attached to the tool's parameters define their characteristics:
 
-OPTIONS:
-      --description <TEXT>  The tool description
-      --force               Override the exist tool file
-  -h, --help                Print help
-  -V, --version             Print version
-```
+- `!`: Indicates that the property is required.
+- `*`: Specifies that the property value should be an array.
+- `+`: Marks the property as required, with the value also needing to be an array.
+- No suffix: Denotes that the property is optional.
 
-```sh
-argc create@tool _test.sh foo bar! baz+ qux*
-```
+### Use aichat
 
-The suffixes after property names represent different meanings.
+AI is smart enough to automatically create tool scripts for us. We just need to provide the documentation and describe the requirements well.
 
-- `!`: The property is required.
-- `*`: The property value must be an array.
-- `+`: The property is required, and its value must be an array.
-- No suffix: The property is optional.
+Use aichat to create a common tool script:
+```
+aichat -f docs/tool.md <<-'EOF'
+create tools/get_youtube_transcript.py
+
+description: Extract transcripts from YouTube videos
+parameters:
+   url (required): YouTube video URL or video ID
+   lang (default: "en"): Language code for transcript (e.g., "ko", "en")
+EOF
+```
+
+Use aichat to create a agent tools script:
+```
+aichat -f docs/agent.md -f docs/tool.md <<-'EOF'
+
+create a spotify agent
+
+index.yaml:
+    name: spotify
+    description: An AI agent that works with Spotify
+
+tools.py:
+  search: Search for tracks, albums, artists, or playlists on Spotify
+    query (required): Query term
+    qtype (default: "track"): Type of items to search for (track, album, artist, playlist, or comma-separated combination)
+    limit (default: 10): Maximum number of items to return
+  get_info: Get detailed information about a Spotify item (track, album, artist, or playlist)
+    item_id (required): ID of the item to get information about
+    qtype (default: "track"): Type of item: 'track', 'album', 'artist', or 'playlist'
+  get_queue: Get the playback queue
+  add_queue: Add tracks to the playback queue
+    track_id (required): Track ID to add to queue
+  get_track: Get information about user's current track
+  start: Starts of resumes playback
+    track_id (required): Specifies track to play
+  pause: Pauses current playback
+  skip: Skips current track
+    num_skips (default: 1): Number of tracks to skip
+EOF
+```
\ No newline at end of file