shugyo-mcp

name	shugyo-mcp
description	Guide for querying company data through Shugyo's digital twin. Teaches a context-first workflow — build understanding of the company's ontology, processes, and metrics, then clarify ambiguity before writing SQL. Use when the user asks any question about their company data via the shugyo-ai MCP server.
argument-hint	[question, e.g. 'what was our revenue last quarter' or 'show team utilization trends']
args	[{"name":"question","description":"The question to answer about company data","required":false,"example":"what was our revenue last quarter?"}]

Help the user answer a question about their company using Shugyo MCP tools: $ARGUMENTS

If $ARGUMENTS is empty, ask the user what they want to know.

The Problem You're Solving

Shugyo is a digital twin of the company — it models the business as an ontology of entities, processes, and metrics backed by real data in BigQuery. When users ask questions, the instinct is to jump straight to discovering tables and running SQL. This produces shallow answers that miss business context. Worse, user questions are often imprecise — they use ambiguous terms, omit timeframes, or conflate related concepts. Querying without first understanding the business model and clarifying the question leads to wrong answers delivered with false confidence.

The workflow below solves both problems: build context first, then use that context to sharpen the question before writing any SQL.

What Kinds of Questions This Covers

Shugyo models the entire company, so this covers any question about company data:

• Financial — revenue, costs, margins, burn rate, runway, invoices, payments
• People & HR — headcount, hiring, attrition, team composition, compensation
• Sales & pipeline — deals, conversion rates, pipeline value, win rates
• Operations — project delivery, utilization, capacity, timelines
• Clients & accounts — client health, retention, contract values, engagement
• Product & usage — feature adoption, active users, engagement metrics
• Cross-domain — correlations across areas (e.g., "does team size affect project margins?")
• Any company-defined KPI — whatever the company tracks in Shugyo

Workflow: Context First, Queries Second

Follow these phases in order. Do NOT skip to SQL.

Phase 1: Understand the Platform

Call get_approach to get the platform overview, data flow, and tool usage guide. This orients you on what Shugyo is and how the data pipeline works.

Phase 2: Build Business Context

Before touching any table, understand what the company tracks and how. Run these calls (parallelize where possible):

1. get_ontology — the business domain model. Shows entities (clients, employees, projects, etc.), their relationships, and which BigQuery tables back them. This is the map of the business.

2. explore_processes_and_metrics — all business processes with their pre-built metrics. A metric may already answer the user's question with vetted SQL — check before writing your own.

3. query_knowledge with the user's question — company-specific terminology, definitions, and business rules. For example, "revenue" might mean something specific (recognized vs. invoiced, including or excluding certain client types).

Phase 3: Narrow Down

Based on what you learned in Phase 2:

• If a pre-built metric answers the question — use get_metric_details to get its full definition including SQL, goal, unit, and category. You may be able to run this SQL directly or adapt it slightly.

• If a process is relevant — use get_process_details to see all its metrics and understand the full business workflow.

• If you need to explore specific tables — now use get_table_context for gotchas, anti-patterns, and vetted query examples. Then get_table_schema for exact column names and types.

• If you need broader table discovery — use discover_tables for the full catalog beyond the ontology.

• If you need query best practices — use get_docs for SQL tips, data glossary, and troubleshooting.

Phase 4: Decompose & Clarify

Now you have business context. Before writing any SQL, use it to stress-test the user's question. Decompose the query and look for:

• Ambiguous terms — Does "revenue" mean recognized, invoiced, or contracted? Does "team" mean a department, a project team, or the whole company? Does "active" have a specific definition in query_knowledge?
• Missing scope — What time period? Which entity subset? (e.g., "our clients" — all clients, or only active ones?)
• Implicit assumptions — "How many people did we hire?" assumes a hiring process exists and has clean data. Does it?
• Logical gaps — A question like "what's our profit margin per project?" requires both revenue and cost data attributed to projects. Does the data model support that join?
• Metric mismatch — The user asks for X, but the closest pre-built metric measures Y. Are they the same thing, or is the difference meaningful?

If you find gaps or ambiguity, ask the user before proceeding. Frame the questions using what you learned — reference specific metrics, entities, or terminology from the ontology so the user can give precise answers. Keep it to 2-3 focused questions max; don't interrogate.

Example: User asks "what's our revenue?" — this is missing a time frame (this month? this quarter? YTD?), and "revenue" itself may have multiple definitions in the company (recognized vs. invoiced vs. contracted). After checking query_knowledge you might learn the company tracks "recognized revenue" and "invoiced revenue" separately. Ask: "Do you mean recognized or invoiced revenue, and for what time period?"

If the question is clear and unambiguous, skip straight to Phase 5. Not every question needs clarification — "how many employees do we have right now?" is probably fine as-is.

Phase 5: Query with Confidence

Only now write and run SQL via run_query. Your query should:

• Use the exact column names confirmed via get_table_schema
• Follow any gotchas from get_table_context (e.g., date filters, null handling, deduplication)
• Prefer vetted SQL patterns from metric definitions or table context over ad-hoc queries
• Respect the 100-row limit — aggregate or filter appropriately

Phase 6: Answer in Business Terms

Present the results using the business language you learned in Phase 2:

• Use the company's terminology (from query_knowledge)
• Reference the process or metric by name if one exists
• Explain what the numbers mean in context, not just raw values
• Flag any caveats (data freshness, known gaps, edge cases from table context)

Key Principles

• Metrics before custom SQL — a pre-built metric is vetted and trusted. Always check explore_processes_and_metrics first.
• Ontology before tables — the ontology tells you how the business models itself. A table name alone doesn't tell you what it means.
• Knowledge before assumptions — terms like "active client", "revenue", or "utilization" have company-specific definitions. Use query_knowledge to learn them.
• Context before schema — get_table_context reveals gotchas that get_table_schema alone won't show (e.g., "filter out status='deleted'" or "use invoice_date not created_at for revenue timing").
• Show your reasoning — briefly tell the user what you found in the ontology/metrics/knowledge, so they can correct misunderstandings before you query.

Available Tools Reference

Tool	Purpose	When to call
get_approach	Platform overview & tool guide	Always first
get_ontology	Business domain model & entity-table mappings	Phase 2 — understand the business
explore_processes_and_metrics	All processes with metric summaries	Phase 2 — check for existing metrics
query_knowledge	Company glossary & business rules	Phase 2 — learn terminology
get_metric_details	Full metric definition with SQL	Phase 3 — when a metric matches
get_process_details	Process with all its metrics	Phase 3 — when a process is relevant
get_table_context	Gotchas, anti-patterns, vetted queries	Phase 3 — before writing SQL
get_table_schema	Column names, types, nullability	Phase 3 — confirm schema
discover_tables	Full table catalog	Phase 3 — when ontology isn't enough
get_docs	Query tips, glossary, troubleshooting	Phase 3 — best practices
run_query	Execute read-only SQL (max 100 rows)	Phase 5 — only after clarification

Anti-Patterns to Avoid

• Jumping to discover_tables + run_query — you'll miss business context and write naive queries
• Ignoring pre-built metrics — the company already defined how to calculate things; don't reinvent
• Assuming column semantics from names — amount could be gross, net, or something else entirely
• Skipping query_knowledge — business terms are often ambiguous without company-specific definitions
• Presenting raw numbers without context — always frame results using the business language you learned
• Querying ambiguous questions without clarifying — "what's our revenue?" has at least 3 interpretations; use what you learned from ontology/knowledge to ask the right follow-up