Add 'Skill or MCP, or both?' guidance and practitioner-language tool surface - #176
Merged
Conversation
The 2026-08-20 Desktop test after the Skybridge-parity merge moved the failure one step forward: mcp-ext-apps-host now engages and logs 'ui.domain validation failed for connector "https://cloud-finops-skills-590a051d.alpic.live/"' - the ROOT url with its trailing slash, while UI_DOMAIN hashed '/mcp'. Skybridge, whose connectors render, hashes https://<host><request-pathname> per request, which for a root-entered connector is exactly the root-with-slash form. Alpic serves the MCP at the root as well as /mcp (verified by a live initialize), so: hash the root form, document the root form as THE connector URL in README and INSTALLATION.md (a variant connects fine but silently disables widget rendering), and correct the wrong 'no trailing slash' note in the CLAUDE.md lesson.
…surface
The tool titles and descriptions answered repo mechanics ('List every
bundled named-pattern playbook') rather than FinOps intent - a
practitioner who has never seen the repo does not ask for 'playbooks',
they ask which VMs run for nothing. Field testing also showed the model
routes advisory questions to tools it can read an intent match for.
- Six tool titles and docstring openings rewritten around practitioner
questions; parameters, returns and semantics unchanged (all three
copies moved together: server.py, README.md, mcp_server/README.md).
- New README section 'Skill or MCP, or both?' with the field-tested
behaviour difference (skill grounds advisory answers, connector wins at
lookups and distribution) and the recommended setup per situation.
- get_reference's description now tells the agent to fetch BEFORE
answering advisory questions - the strongest routing lever available at
the tool layer.
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two changes from the cycle-2 field test, stacked on #175 (merge that first - this branch contains its commit until then):
1. README section "Skill or MCP, or both?" - the field-tested behaviour difference, stated for users: the skill is pushed into context and grounds advisory answers (commitment sizing, chargeback design); the connector wins at lookups, distribution (paste one URL), faceted queries and widgets. Recommended setup per situation, including the AI Pricing Hub pairing.
2. Practitioner-language tool surface. The six tool titles and description openings answered repo mechanics ("List every bundled named-pattern playbook") rather than FinOps intent - "Show me the idle waste playbooks" means nothing to a practitioner who has never seen the repo. Rewritten around the questions people actually ask ("which VMs run for nothing", "how should we size Savings Plans"). Parameters, returns and semantics unchanged; the three copies moved together per the checklist (server.py docstrings, README.md table, mcp_server/README.md table).
get_referencenow instructs fetching BEFORE answering advisory questions - the strongest routing lever available at the tool layer, aimed at the P05 improvisation gap.102 tests pass; docs-drift and skill-description guards green.