get_build_insights_report

Get a computed Build Insights Report over build history: Health Snapshot + Trends, Root Cause, Artifact Health, Workflow Quality, Queue Time, and Maturity Assessment analysis, aggregated server-side.

Unlike get_build_history_report (which returns raw paginated records), this tool fetches every page internally, computes percentiles/grouping/MTTR/flaky detection in Python, and returns only the small aggregated result. Sections that can't be computed from the available data (e.g. a field stripped by an Appcircle role restriction) are omitted rather than rendered as zeros or fabricated, and flagged in meta.omitted_sections / meta.omitted_subsections. Only the current-period build history fetch is mandatory -- every other fetch (previous period, profiles, queue waiting, signing identities, per-profile workflow/trigger/configuration data) is best-effort: a 401/403 from a token lacking permission for that specific resource (e.g. an admin-only endpoint) omits just the dependent section/subsection instead of failing the whole call, and is listed in meta.failed_fetches.

A main-org access token sees build history spanning every sub-organization, but can only enumerate its own org's profiles (the Appcircle API itself enforces this -- not something this tool can fetch around). By default the report is scoped to the token's own organization: build records whose profile isn't in that token's own profile list are excluded before any section is computed, so every section always means the same scope. Set include_sub_orgs=True to keep cross-org records in history-derived metrics (Health Snapshot, Root Cause, Artifact Health, Speed/Reliability) -- Workflow Quality/Discipline/Security for those profiles still can't be resolved (the API limitation doesn't go away), so they're omitted for those specific profiles rather than fabricated, and listed in meta.unresolved_profiles. queue_time has no profile field to scope by, so it's always a tree-wide aggregate regardless of this flag.

Args: start_date: Optional start date (format: "YYYY-MM-DD") for the current period. end_date: Optional end date (format: "YYYY-MM-DD") for the current period. If both start_date and end_date are omitted, defaults to the last 30 days. If only one is given, the other is filled to a 30-day-wide window. sections: Optional list of sections to compute. Subset of ["health_snapshot", "root_cause", "artifact_health", "workflow_quality", "queue_time", "maturity_assessment"]. Defaults to all six. Invalid section names return a validation error. include_sub_orgs: If True, keep cross-org build records in history-derived metrics instead of filtering them to the token's own org (default False). See the note above on what stays unresolved either way.

Returns: Standard envelope (see docs/tool_contract.md): - Success: success (true), data (date_range, sections.health_snapshot, sections.root_cause, sections.artifact_health, sections.workflow_quality, sections.queue_time, sections.maturity_assessment), meta (requested_sections, omitted_sections, omitted_subsections, failed_fetches, cross_org_builds_excluded, unresolved_profiles). - Error: success (false), error (tool, type, message, details).

Examples: Full report, last 30 days: get_build_insights_report() Root cause only, custom range: get_build_insights_report( start_date="2026-01-01", end_date="2026-01-31", sections=["root_cause"] ) Include cross-org records from a main-org token: get_build_insights_report(include_sub_orgs=True)