scenario-admin-analytics

Scenario 管理者向け分析

概要

Scenario MCP の利用データを、回答、CSV、Markdown、グラフ付き PDF、またはオフラインダッシュボードに変換します。Scenario のデータ収集はすべて MCP 上で行います。レポート用スクリプトで直接 API を呼び出したり、SDK を使用したり、ブラウザーをスクレイピングしたり、認証情報を扱ったりしないでください。接続設定には scenario スキルを使用します。ここに記載された関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で処理する場合は、ツールのスキーマに基づいて進め、不足していることを明示してください。

teams_list を使って顧客を特定し、必要に応じて projects_list({team_id}) を使います。ユーザーが選択したスコープを再利用してください。複数の名前が一致する場合は、見つかった選択肢を提示して確認します。無人で処理する場合は、タスクに明示されたチーム／プロジェクト ID のペアを使用し、それ以外の場合は停止して選択肢を列挙してください。黙って最初の候補を選んではいけません。組織全体を対象とするリクエストでは、アクセス可能なコンテキストプロジェクトと scope:"team" を使用します。対象となるのは認証情報でアクセスできるプロジェクトであり、追加のアクセス権が付与されるわけではありません。プロジェクトを対象とする場合は scope:"project"（デフォルト）を使用します。project_id は認証コンテキストとデフォルトの分析フィルターを指定します。project_ids は同じチーム内の別のプロジェクトを選択するもので、scope:"team" と併用できません。選択した ID は重複を取り除いてください。チーム全体の合計に各プロジェクトの小計を加えたり、プロジェクトごとのユニークユーザー数を合算したりしないでください。

クイックリファレンス

質問	MCP の使用状況データ	計算
上位 3 モデル	modelUsages	CU の場合は totalCU、頻度の場合は totalJobs で並べ替え、両方を表示します。
3 か月分の全モデルの CU	modelUsages.daily を追加	すべてのモデルをエクスポートし、時間バケットを UTC の月ごとにまとめます。
最も多くの CU を消費したのは？	consumption、entities	value で順位付けし、userId を entities.users[].id に結合します。
ユーザーごとの上位モデル	1 つの user_ids ID でスコープした usage を繰り返す	各レスポンスのモデルを順位付けし、CU とジョブ数を含めます。
10 モデルについての上位 5 ユーザー	同じユーザーごとのクエリ	全体の上位 10 モデルを選び、それぞれについて 5 人の識別情報を順位付けします。
差異の説明	usages.daily、activity	記録された根拠を確認します。アクティビティ全体が必要な場合は、完了するまで activityPagination.nextOffset をたどります。

スキーマが見つからない場合や古い場合は、scenario_tools_search({query:"usage",limit:1}) で現在のスキーマを確認します。通常は、表示されている usage を直接呼び出します。カタログのみの場合は、arguments ではなく scenario_tool_execute_read({name:"usage",parameters:{...}}) を使用します。デプロイ後もホストが古い直接呼び出しシグネチャを保持していることがあります。最新のカタログに不足しているフィールドがあれば、そのスキーマを指定して同じ読み取り実行ツールを使うか、再接続してください。古いホストのシグネチャは、機能がないことを示すものではありません。呼び出しは公開されている使用状況リファレンスとライブカタログに基づいて行います。

日付は必ず両方指定します。範囲の境界は両端を含みます。3 月全体を指定する場合、終了日時は 2026-03-31T23:59:59.999Z です。時間バケットは UTC であることを明記します。日付の指定がない質問では、直近の完了済み 30 日間を想定します。「過去 3 か月」の場合は、直近の完了済み暦月 3 か月を想定し、期間を明記します。日付を指定しない API 呼び出しのデフォルトは 31 日間であり、全期間ではありません。今日の数値は暫定値です。API には範囲の上限がありますが、固定の上限を推測してはいけません。大きな範囲が拒否された場合は、重複しない両端を含む期間に分割し、各ソースを保持して、加算可能な指標を合算します。ユニークな識別情報の件数は合算しません。

まず概要 JSON を取得します。レポートでは include:["modelUsages.daily","entities"] を追加します。短い期間では、時間バケットが日単位より細かくなることがあります。タイムスタンプごとに集計してから UTC の日単位にまとめ、重複するタイムスタンプは除外します。activity は activity_offset を使って 1 回につき最大 100 件でページネーションされます。完了したと推測せず、返された次のオフセットをたどってください。概要は各アクティビティページで繰り返されるため、1 回だけ数えます。通常の順位付けでは activity を避けてください。

会計処理と信頼性

totals.totalCU は、割引適用後の consumption[].value を合計した値です。割引適用前の consumption[].total は value + discount と等しくなります。モデルの totalCU は、割引適用後の時間帯ごとの cost を合計した値です。割引を再度差し引かないでください。API キーの CU はその一部です。小数、ゼロ、全額割引された行、負の値はそのまま保持してください。ジョブ数はモデルの実行回数を示すもので、正常に生成されたアセット数ではありません。

返された scope と日付を検証し、消費量を全体の CU と、時間帯別の値をモデルのサマリーと、ユーザーごとのモデル合計をフィルターなしのモデルデータと照合してください。scope の返却値には適用されたフィルターが記録されますが、すべての顧客プロジェクトにアクセスできることを証明するものではありません。確認できた範囲と結果をそのまま示してください。検証済みデータに、古い「未検証の消費量」という警告を引き継がないでください。

モデル系列が示すのは生成アクティビティであり、別途記録される返金やモデル以外の操作は含まれません。そのため、モデルの CU が全体の消費 CU と一致しない場合があります。差分は、その原因を断定せずに示してください。説明を求められた場合は、使用量の各セクションを確認してください。差分をモデルに割り当てたり、重複する使用タイプのカテゴリを合算したり、消費量の代わりにジョブの請求スナップショットを使ったりしないでください。照合に失敗した場合は、影響を受ける帰属情報のみを保留し、正確な不一致を報告して、MCP を通じて調査してください。

ユーザー／モデルのマトリックスを作成する場合は、consumption[].userId ごとに、同じスコープと期間を指定した使用量クエリを 1 回ずつ実行し、ゼロや負の値を含む行もすべて取得してください。独立したユーザーサマリーとモデルサマリーを割合で結合しないでください。網羅性を主張する前に、すべてのモデル CU とジョブ数を照合してください。ID が不足している場合は、帰属先を推測せず、MCP の ID／アクティビティメタデータを調査してください。返されたエンティティを使って名前を解決してください。名前がなく、受け取り手が個人を特定できるユーザー情報を必要とする場合は、team_members_list を検出し、返されたメールアドレスを ID で結合してください。安定した ID は内部で保持し、メタデータで識別できる場合は API ID を区別してください。ID の種類が不明な場合は、不明のままにしてください。「最も使用された」の指標が指定されていない場合は、ジョブ数で順位を付け、CU も示してください。CU が明示的に指定された場合は、CU で順位を付けてください。同順位は安定した ID で決定的に並べ替えてください。上位 N 件の行には、両方の指標を含めてください。

キャッシュ、出力、環境のフォールバック

製品名ではなく、機能を確認してください。ファイルと Python を使用する場合は、同梱の オフラインヘルパーを使用します。エージェントが MCP データを収集し、スクリプトは ローカルのスナップショットのみを変換します。エンベロープ、コマンド、依存関係、 対応フィルター、キャッシュの検証については、ローカルレポートをお読みください。 ダッシュボードテンプレートでは、 Scenario の公開サイトの温かみのあるペーパー、チャコール、テラコッタの配色を使用し、 ローカルフォントにフォールバックします。

接続／アカウントの名前空間、スキーマバージョン、チーム、コンテキストプロジェクト、スコープ、選択した プロジェクト／ユーザー ID、正確な日付、セクション、アクティビティのオフセットごとにキャッシュします。 デフォルトの TTL は 1 時間です。「更新」するとキャッシュをバイパスします。ユーザー／モデルに関する質問にも、 ユーザーごとの最新スナップショットが必要です。元の取得時刻を保持してください。エクスポートを再インポートしても、 データを最新として扱うことはできません。要約のみのデータでは、新たな傾向に関する質問には回答できません。 期限切れのデータは、履歴データ／オフラインデータであることを明記すれば利用できます。接続の変更や集計／スコープ設定の修正があった場合、 影響を受けるキャッシュを無効にします。プライベートなスナップショットはリポジトリの外に保管し、 認証情報や不要な個人データを含めず、リクエストがあれば削除してください。取得時刻は、上流データの鮮度を保証するものではありません。

エフェメラルな実行環境では、セッションファイルを使用し、その保存期間を説明してください。MCP は利用できても ファイル／実行機能がない場合は、小規模な質問には直接回答し、Markdown またはコードフェンス付き CSV を提示してください。キャッシュはセッション内に限られます。 PDF を生成できない場合は、対応していれば、ローカルで印刷可能な HTML を提示してください。保存されていないファイルや レンダリングされていない PDF が存在すると主張してはいけません。MCP がない場合は、出所と経過時間を明記して提供済みの過去の MCP スナップショットを使用するか、 接続できないことを報告してください。Scenario データを取得できる別の手段はありません。

まず、対象範囲、日付、指標、取得時刻を示して、質問に直接答えてください。レポートには、消費 CU、モデルジョブ、 モデルの幅、集中度、傾向、ID 別ランキング、照合結果を含めます。このヘルパーは、CU／ジョブの並べ替え、ユーザーあたりのモデル数の設定、月次 CSV、 およびユーザーごとの時間バケットが存在する場合の、ユーザー／モデル／日付によるダッシュボードのフィルタリングに対応しています。期間全体の総消費量と ID 別消費量は、フィルタリングされた生成アクティビティとは別に表示し、それぞれ区別がわかるようにします。ダッシュボードを更新するには、MCP から再度データを取得する必要があります。このスキルの一部として、顧客データを公開してはいけません。

対応していないリクエストは「MCP では利用できません」に分類し、不足している証拠と、対応可能な代替手段があればそれを記載してください。利用状況だけでは、ROI、節約できた時間、チケットへの帰属、生成された出力の採用状況、過去の対象席数、または定着率を立証できません。権限エラー、結果が空であること、対象範囲の不足、未対応の指標は、それぞれ異なる結果です。

実践例

2026年9月17日のリクエスト：「すべてのプロジェクトを対象に、ユーザーごとのCU上位5モデルをジョブ数とともに提示してください。3か月分のCSVとPDFも作成してください。」

1. チームと、アクセス可能なコンテキストプロジェクトを特定します。直近3つの完了した暦月として、6月1日から8月31日までを指定します。必要に応じて、現在の使用状況スキーマを確認します。
2. ユーザーの網羅状況を含め、キャッシュを正確に確認します。キャッシュにない場合は、次を呼び出します。 usage({team_id:"<selected team>",project_id:"<context project>",scope:"team",start_date:"2026-06-01T00:00:00Z",end_date:"2026-08-31T23:59:59.999Z",include:["modelUsages.daily","entities"],response_format:"json"})。 プレースホルダーは検出結果から取得します。
3. 各消費アイデンティティについて、user_ids:["<returned identity ID>"]を指定して同じクエリを繰り返します。完全な{query,response,fetched_at}エンベロープをそれぞれ保存します。日付、スコープ、モデルごとの照合を確認します。これらのユーザー別合計を親の合計に加算しないでください。
4. 親とユーザー別のエンベロープを取り込んだ後、--rank-by cu --top-models-per-user 5 --pdfでレンダリングします。回答に加え、モデル別・月別のCSV全体とユーザー別ランキングを返します。以降の上位3モデルやジョブ数順の質問では、これらの新しいスナップショットをオフラインで再利用します。
5. PDFのすべてのページを画像に変換し、納品前にレイアウトを確認します。視覚的な検証ができない場合は、その旨を明示します。ダッシュボードのフィルターを既知の合計値と照合してテストします。顧客の成果物はローカルに保持します。

よくある間違い

• 認証用プロジェクトだけが分析フィルターとして使えると見なしたり、チームスコープによってより広い権限が得られると思い込んだりすること。
• 終了日を排他的に扱うこと、生涯の合計だと思い込むこと、古いスキーマを使うこと、修正前にキャッシュされた数値を使うこと。
• 割引を二重に差し引くこと、APIの内訳を加算すること、モデルのアクティビティを全体の消費量と一致させようとすること。
• 推測に基づく返金理由、ユーザーとモデルの比例配分による結合、または不完全な履歴を完全な使用状況として報告すること。
• 分母を示さずにCUを「採用率」と呼ぶこと、顧客のスナップショットを公開すること、またはMCP以外の代替手段を使うこと。