docs: Cleanup agent docs, tools docs, and intro (#2300)

* add agent documentation

* docs changes

* add more docs

* fix typo

* docs cleanups

Author: chaynabors

docs/introduction.md

@@ -2,8 +2,4 @@
 
 Welcome to the Amazon Q CLI developer documentation.
 
-These docs are a work in progress and subject to change. As of now, they do not represent latest stable builds, instead documenting the functionality of development builds.
-
-For information on configuring agents, see [The Agent Format](./the-agent-format.md)
-
-For information on managing knowledge, see [Knowledge Management](./knowledge-management.md)
+These docs are experimental, work in progress, and subject to change. As of now, they do not represent latest stable builds, instead documenting the functionality of development builds.

docs/native-tools.md

@@ -1,8 +1,16 @@
-## execute_bash
+# Native tools
 
-Execute the specified bash command.
+- [`execute_bash`](#the_execute_bash_tool) — Execute a shell command.
+- [`fs_read`](#the_fs_read_tool) — Read files, directories, and images.
+- [`fs_write`](#the_fs_write_tool) — Create and edit files.
+- [`gh_issue`](#the_gh_issue_tool) — Open a GitHub issue template.
+- [`knowledge`](#the_knowledge_tool) — Store and retrieve information in a knowledge base.
+- [`thinking`](#the_thinking_tool) — Internal reasoning mechanism.
+- [`use_aws`](#the_use_aws_tool) — Make AWS CLI API calls.
+
+## The `execute_bash` tool
 
-### Config
+Execute the specified bash command.
 
 #### Schema
 
@@ -34,12 +42,10 @@ Execute the specified bash command.
 }
 ```
 
-## fs_read
+## The `fs_read` tool
 
 Tool for reading files, directories and images.
 
-### Config
-
 #### Schema
 
 ```json
@@ -65,12 +71,10 @@ Tool for reading files, directories and images.
 }
 ```
 
-## fs_write
+## The `fs_write` tool
 
 Tool for creating and editing files.
 
-### Config
-
 #### Schema
 
 ```json
@@ -100,36 +104,28 @@ Tool for creating and editing files.
 }
 ```
 
-## gh_issue
+## The `gh_issue` tool
 
 Opens the browser to our GitHub template for reporting issues with `q`.
 
-### Config
-
 This tool has no configuration.
 
-## knowledge
+## The `knowledge` tool
 
 Store and retrieve information in knowledge base across chat sessions
 
-### Config
-
 This tool has no configuration.
 
-## thinking
+## The `thinking` tool
 
 Thinking is an internal reasoning mechanism improving the quality of complex tasks by breaking their atomic actions down.
 
-### Config
-
 This tool has no configuration.
 
-## use_aws
+## The `use_aws` tool
 
 Make an AWS CLI api call with the specified service, operation, and parameters.
 
-### Config
-
 #### Schema
 
 ```json

docs/the-agent-format.md

@@ -4,13 +4,13 @@ The agent configuration file for each agent is called its _manifest_. It is writ
 
 Every manifest file consists of the following sections:
 
-- [`name`](#the-name-field) --- The name of the agent.
-- [`version`](#the-version-field) --- The version of the agent.
-- [`description`](#the-description-field) --- A description of the agent.
-- [`mcpServers`](#the-mcp-servers-field) --- The MCP servers the agent has access to.
+- [`name`](#the-name-field) — The name of the agent.
+- [`version`](#the-version-field) — The version of the agent.
+- [`description`](#the-description-field) — A description of the agent.
+- [`mcpServers`](#the-mcp-servers-field) — The MCP servers the agent has access to.
 - [`tools`](#the-tools-field) --- The tools available to the agent.
-- [`allowedTools`](#the-allowed-tools-field) --- Tools that can be used without prompting.
-- [`toolsSettings`](#the-tools-settings-field) --- Configuration for specific tools.
+- [`allowedTools`](#the-allowed-tools-field) — Tools that can be used without prompting.
+- [`toolsSettings`](#the-tools-settings-field) — Configuration for specific tools.
 
 ### The `name` field