fix(search_assets_tool): trap wrong params (search_query, attributes, filters, dsl, convex_context)

[mothership-ai]

Session owner: @abhinavmathur-atlan

Summary

• LLMs send 5 invalid parameter names to search_assets_tool (~36 errors/30d): search_query, attributes, filters, dsl, convex_context
• FastMCP hard-rejects these before the function runs, giving opaque errors that don't help the LLM self-correct
• Added all 5 as trapped decoy parameters (None defaults) that return clear redirect error messages pointing to the correct tool or parameter name
• Added a "COMMON MISTAKES" section to the docstring so LLMs can avoid these errors in the first place

How it works

Instead of letting FastMCP reject these with a generic "unexpected parameter" error, we accept them but immediately return a structured error dict that tells the LLM exactly what to do:

• search_query → "Wrong tool: call semantic_search_tool(query=...) instead"
• attributes → "Wrong parameter: use include_attributes"
• filters → "Wrong parameter: use conditions / negative_conditions / some_conditions"
• dsl → "Wrong tool: call get_assets_by_dsl_tool(dsl_query=...) instead"
• convex_context → "Invalid parameter: does not exist on any tool"

Follows the same pattern as agent-toolkit-internal PR #162 (which trapped query and asset_types).

Test plan

• Verify search_assets_tool(search_query="test") returns the redirect error
• Verify search_assets_tool(attributes=["name"]) returns the redirect error
• Verify search_assets_tool(filters={"type": "Table"}) returns the redirect error
• Verify search_assets_tool(dsl={"query": {}}) returns the redirect error
• Verify search_assets_tool(convex_context="test") returns the redirect error
• Verify normal search_assets_tool(conditions=...) calls still work unchanged
• Monitor for reduction in these ~36 errors/30d after deployment

Fixes: AICHAT-830

🤖 Generated with Claude Code