Parse tool descriptions from docstring

[vikigenius]

Is your feature request related to a problem? Please describe.
Having to write down the names of all arguments again and their description in the tool macro is annoying

Describe the solution you'd like
In python pydantic-ai for example just parses the docstring

@my_agent.tool
async def search_documents(query: str, max_docs: int):
    """Search documents for query.

    Args:
        query: The query to search
        max_docs: Maximum documents to return
    """

Can we do something similar here? Parse the doc comments instead for the tool spec

[timonv]

Thanks for opening an issue @vikigenius. Any suggestions on what it should look like? The benefit of having it in the attribute macro, is that we can enforce checking if everything matches and give (at least attempt to) helpful errors to get the syntax right. I like the idea of simplifying like this, recon it's also possible with doc comments.

[vikigenius]

Unlinke python I don't think Rust has any officially specified docstring formats rust-lang/rust#57525

So something like

/// Search documents for a query.
///
/// # Arguments
/// - `query`: The query to search
/// - `max_docs`: Maximum documents to return
#[tool] // or #[swiftide::tool]
async fn search_documents(query: String, max_docs: usize) -> Vec<Document> { ... }

We can then allow partial overriding through the original mechanism, the macro will take the highest priority

/// Search documents for a query.
///
/// # Arguments
/// - `query`: The query to search
/// - `max_docs`: Maximum documents to return
#[tool(description = "Search documents", args(max_docs = "Cap on returned docs"))]
async fn search_documents(query: String, max_docs: usize) { ... }

So we can still rely on the macro to extract params from function signature, and if args are missing in the macro itself we can try to extract from docs if possible and if that doesn't work we can emit warnings

[timonv]

@vikigenius I love this idea! I personally don't have the time right now to implement this, but if you're interested in contributing with some macro fu, I'd love to see it. As long as everything is backwards compatible.