{
    "id": "search_apps",
    "name": "Search BlackOrder apps",
    "description": "Ranked search over BlackOrder applications. Returns compact records with canonical_url and official_page_url (the page where a person downloads; files are never returned).",
    "version": "2.1.0",
    "effect": "read",
    "generated": false,
    "endpoint": "https://blackorder.io/api/agent/tools/search_apps",
    "method": "POST",
    "mcp": {
        "url": "https://blackorder.io/mcp",
        "tool": "search_apps"
    },
    "inputSchema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Free-text query, e.g. \"professional audio editor\"."
            },
            "platform": {
                "type": "string",
                "enum": [
                    "macOS",
                    "iOS",
                    "iPadOS"
                ],
                "description": "Platform filter; BlackOrder publishes macOS, iOS and iPadOS software."
            },
            "category": {
                "type": "string",
                "enum": [
                    "audio",
                    "video",
                    "developer-tools",
                    "network",
                    "security",
                    "system",
                    "productivity",
                    "utilities",
                    "weather"
                ],
                "description": "App category."
            },
            "free": {
                "type": "boolean",
                "description": "true = free apps only, false = explicitly paid apps only. Unknown prices match neither filter."
            },
            "language": {
                "type": "string",
                "enum": [
                    "en",
                    "it"
                ],
                "description": "Language of the answer and of the pages returned (default en). With \"it\" the text is Italian and canonical_url points to the Italian page.",
                "default": "en"
            },
            "capabilities": {
                "type": "array",
                "items": {
                    "type": "string"
                },
                "description": "Words that must appear in the app's capabilities (e.g. [\"transcription\"])."
            },
            "limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 50,
                "default": 10
            }
        },
        "additionalProperties": false
    },
    "outputSchema": {
        "type": "object",
        "properties": {
            "publisher": {
                "type": "string"
            },
            "source": {
                "type": "string"
            },
            "canonical_domain": {
                "type": "string"
            },
            "total": {
                "type": "integer"
            },
            "language": {
                "type": "string"
            },
            "results": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "canonical_url": {
                            "type": "string",
                            "format": "uri"
                        },
                        "official_page_url": {
                            "type": "string"
                        },
                        "name": {
                            "type": "string"
                        },
                        "title": {
                            "type": "string"
                        },
                        "description": {
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "version": {
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "minimum_os": {
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "architecture": {
                            "type": [
                                "array",
                                "null"
                            ],
                            "items": {
                                "type": "string"
                            }
                        },
                        "price": {
                            "type": [
                                "number",
                                "null"
                            ]
                        },
                        "currency": {
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "is_free": {
                            "type": [
                                "boolean",
                                "null"
                            ]
                        },
                        "signed": {
                            "type": [
                                "boolean",
                                "null"
                            ]
                        },
                        "notarized": {
                            "type": [
                                "boolean",
                                "null"
                            ]
                        },
                        "facts": {
                            "type": "object",
                            "additionalProperties": {
                                "type": "object",
                                "required": [
                                    "value",
                                    "source",
                                    "verified_at",
                                    "freshness",
                                    "confidence",
                                    "type"
                                ],
                                "properties": {
                                    "value": {},
                                    "source": {
                                        "type": "object",
                                        "required": [
                                            "url",
                                            "publisher",
                                            "type"
                                        ],
                                        "properties": {
                                            "url": {
                                                "type": "string",
                                                "format": "uri"
                                            },
                                            "publisher": {
                                                "type": "string"
                                            },
                                            "type": {
                                                "type": "string"
                                            }
                                        }
                                    },
                                    "verified_at": {
                                        "type": "null"
                                    },
                                    "freshness": {
                                        "type": "object",
                                        "properties": {
                                            "retrieved_at": {
                                                "type": "string",
                                                "format": "date-time"
                                            },
                                            "max_age_seconds": {
                                                "type": "integer"
                                            }
                                        }
                                    },
                                    "confidence": {
                                        "enum": [
                                            "publisher_declared",
                                            "unknown"
                                        ]
                                    },
                                    "type": {
                                        "const": "publisher_statement"
                                    },
                                    "verification_scope": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    },
                    "additionalProperties": true
                }
            }
        },
        "required": [
            "publisher",
            "source",
            "canonical_domain",
            "results"
        ],
        "additionalProperties": true
    },
    "examples": [
        {
            "input": {
                "query": "audio",
                "free": true,
                "language": "it"
            },
            "expected": "Matching free applications from the current catalog."
        }
    ],
    "fallback": {
        "url": "https://blackorder.io/agents/catalog",
        "text": "https://blackorder.io/llms-full.txt",
        "limitations": "Publisher catalog; automatic compatibility evaluation requires REST or MCP."
    }
}