docs: initial commit of developer information about tools

[grahamwhiteuk]

No description provided.

[Tomas2D]

Great work! 🚀

However, I see some room for improvement, like:

• Provide a better explanation of Tool class generics and related generics.
• Mention that zod schema is under the hood, converted to JSONSchema, and validated via Ajv. When the input is invalid, ToolInputError is thrown.
• Mention that if one wants to use zod effects (somehow modify/transport/improve the validation process), it can be achieved via override validateInput method (see arxiv tool where it is done).
• Show an example with DynamicTool (feel free to see tests for inspiration).
• Clarify content of BaseToolOptions and BaseToolRunOptions interfaces.
• Use camelCase in naming files (helloworld.ts -> helloWorld.ts).
  Understanding why a tool must return a class that extends BaseToolOutput is crucial. This class provides you with the getTextContent() method that the agent/llm can use, ensuring the proper functioning of your tool.

[Tomas2D]

• You can also use JSONSchema (but zod is recommended).
• Mention that inputSchema must always be an object and zod effects are not supported (z.object().transform(...)`). (https://github.com/i-am-bee/bee-agent-framework/blob/main/src/internals/helpers/schema.ts#L30-L41)
• inputSchema must be a function (either async or sync, but it must be a function due to internals).

[grahamwhiteuk]

This comment contradicts the comment at the top of the review. Would it be preferable to inform the users via this documentation that zod effects are not supported, or that they can be supported by that requires overriding the validateInput function?

[grahamwhiteuk]

I've attempted an initial resolution in 3483a55 but this may need to be changed as a result of my above observation.

[Tomas2D]

Zod effects are basically some extra "application level" transformations that are not transferable to JSON Schema. But the framework (under the hoods) converts it to a JSON Schema. So to do something like "zod effects" you have to specify inputSchema without them and do post-validation manually later in validateSchema method.

The inputSchema definition must always be an object and pass validation by the validateSchema() function defined in schema.ts.

This statement may sound like you are forcing the user to implement this feature. Either remove the statement or provide a simple example.

[Tomas2D]

Consider adding a link from README.md to tools.md

[grahamwhiteuk]

Consider adding a link from README.md to tools.md

Fixed in ac327b0 (the link will be broken until this PR is merged as the tools file doesn't currently exist on the main branch)

[Tomas2D]

Please add one of the following secrets to your fork so the GitHub action can pass E2E Tests.

GENAI_API_KEY="..."
WATSONX_API_KEY="..."
OPENAI_API_KEY="..."

One of them should be enough (ideally BAM - GENAI_API_KEY)

[grahamwhiteuk]

GENAI_API_KEY is now added and the above comments are addressed in f94bea5