feat(skill): rebuild discovery around find_tools

[zzir]

Change Type

• Routing logic change (SKILL.md)

Description

The skill had drifted several server versions behind, to the point of being
actively wrong:

• The execute examples still used the retired aggregate-dispatch model
  (agentkey_social with a nested path, agentkey_search with type="news").
  Those calls now 400 — core.Lookup("news") has no match. The whole "Common
  Calls" section was removed rather than repaired: find_tools is accurate
  enough that hardcoded no-discovery shortcuts are pure decay.
• Only 4 of the 9 categories were documented — finance, ecommerce, business,
  weather and travel were unreachable in practice.
• agentkey_account was listed as an MCP tool; it is execute_tool(name=…).
• The upstream-failure fallback the server sends in its own instructions
  (sibling surface, sibling version, alternate provider) was missing.

Discovery is now a single find_tools path (q= / prefix= / both / neither),
with list_tools marked deprecated. No concrete Provider/Operation name
appears anywhere in the skill — names go stale, and a stale example teaches a
name the model will later hallucinate.

references/cost-aware.md and references/setup.md are synced to match.

Important

Depends on server-side find_tools prefix= support shipping first. Please
hold the merge until that is live, since merging cuts a release.

Checklist

• No knowledge added to SKILL.md (routing logic only)
• Reference guides follow the existing structure

_{The "New social platform" / "New service or provider" sections don't apply
and were removed. Heads-up: they reference references/social/ and
references/<category>/, which no longer exist in this repo, and the
"standard structure" section they point to is absent from CONTRIBUTING.md.}

---

Contributor Agreement

• I confirm my contribution is licensed under the Apache License, Version 2.0 (see LICENSE).

[Copilot]

Pull request overview

Updates the AgentKey skill routing documentation to remove stale, server-version-dependent tool naming and make discovery consistently flow through find_tools, aligning SKILL guidance and reference docs with the current MCP catalog model.

Changes:

• Replaced legacy list_tools/aggregate-dispatch examples with a unified find_tools → describe_tool → execute_tool discovery/execution flow.
• Expanded and clarified catalog coverage (all major categories) and added documented upstream-failure fallback strategies.
• Synced setup and cost-aware reference guides to reflect the new discovery-first approach and list_tools deprecation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
skills/agentkey/SKILL.md	Rebuilds skill routing/discovery guidance around find_tools and removes stale hardcoded operation examples.
skills/agentkey/references/setup.md	Updates setup reference to reflect the current tool surface (and list_tools deprecation status).
skills/agentkey/references/cost-aware.md	Adjusts batch-cost guidance to leverage find_tools cost and updates terminology/workflow.

Suppressed comments (2)

skills/agentkey/SKILL.md:59

• This line states tool names are “never” written by the agent, but the same section just introduced an explicit exception (execute_tool(name="agentkey_account")). Consider qualifying the statement to avoid a direct contradiction in the routing rules.

Every call follows the same three steps. Tool names are **never** written by you — each step consumes the exact string the previous step returned.

skills/agentkey/references/cost-aware.md:61

• This paragraph uses cost_per_call, but earlier in this doc the per-call number is referred to as cost (from find_tools) or credits_per_call (from describe_tool). Using one term here avoids confusion about what to divide by.

If the estimate **exceeds** the remaining allowance, do not start the batch. Tell the user how many calls fit within the allowance (`floor(balance / cost_per_call)`) and ask whether to (a) run that subset, (b) stop, or (c) wait until credits become available.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lxcong]

@claude review

[github-actions]

🤖 Claude security review requested by @lxcong. Running against HEAD 1ff4abbb4e02a4fc935ae4301989c436d13e9a92...

[claude]

🤖 Claude security review — HEAD: 1ff4abb

Scope: Documentation-only — SKILL.md, references/cost-aware.md, references/setup.md; rebuilds discovery flow around find_tools, deprecates list_tools

✅ No security or convention issues found.

Review triggered by @lxcong
via @claude review.