Conversation
… PR 2) Applies the TDQS template from docs/tdqs-style-guide.md to every Meta Ads tool not covered by PR #43. Files touched: - _tools_meta_ads_creatives.py (9 tools: creatives, images, videos) - _tools_meta_ads_audiences.py (9 tools: audiences, pixels) - _tools_meta_ads_insights.py (8 tools: insights, analysis) - _tools_meta_ads_catalog.py (10 tools: catalogs, products, feeds) - _tools_meta_ads_conversions.py (3 tools: Conversions API) - _tools_meta_ads_leads.py (5 tools: lead forms, leads) - _tools_meta_ads_other.py (14 tools: split tests, ad rules, page posts, Instagram) Notably rewrites meta_ads.creatives.list - the TDQS lowest-scoring tool in mureo at 2.1/5 - to a full description covering returned fields, read-only semantics, pagination defaults, and sibling-tool differentiation. All 173 tools still load; docker build + MCP initialize + tools/list verified end-to-end. No behavioral changes - descriptions and parameter schema hints only.
6 tasks
hyoshi
added a commit
that referenced
this pull request
Apr 24, 2026
* feat(mcp): rewrite lowest-5 TDQS tool descriptions (PR 3 pilot) Targets the five tools currently bottlenecking the Glama server-level Tool Definition Quality Score (TDQS = 0.6*mean + 0.4*min = 3.36, B): - google_ads.landing_page.analyze (was 2.4/5, the min) - google_ads.performance.report (was 2.5/5) - google_ads.schedule_targeting.list (was 2.5/5) - search_console.sitemaps.submit (was 2.5/5) - google_ads.search_terms.report (was 2.6/5) Rewrites follow docs/tdqs-style-guide.md: specific verb, returned fields, side effects, sibling differentiation, parameter format hints. Adds _CUSTOMER_ID_PARAM and _PERIOD_PARAM reusable fragments to _tools_google_ads_analysis.py (same pattern already adopted by _tools_google_ads_campaigns.py and _tools_meta_ads_campaigns.py in PRs #43 and #44). No tool name, required-field, or handler dispatch changes -- this is purely description and schema metadata. Tool count remains 173. Goal: lift server TDQS to A tier (>= 3.5) by raising the minimum. If effective, the remaining ~46 C/B- tools get the same treatment in a follow-up PR to carry quality_grade from B to A (AAB to AAA composite grade). * fix(mcp): correct factual claims in TDQS pilot descriptions Code review flagged CRITICAL/HIGH/MEDIUM factual errors in the return- shape and side-effect claims added by the previous commit. A TDQS rewrite whose goal is "help agents call the tool correctly on first try" cannot ship with descriptions that contradict the mapper. All changes are description-only; schemas, tool names, required fields, and handlers remain unchanged. CRITICAL - google_ads.performance.report: return shape is {campaign_id, campaign_name, metrics:{...}} per mappers.map_performance_report and client.get_performance_report GAQL. Previous description claimed flat fields and added status / conversion_value / conversion_rate that are neither SELECTed nor mapped. Rewritten to match the actual nested metrics object (impressions, clicks, cost_micros, cost, conversions, ctr, average_cpc_micros, average_cpc, cost_per_conversion_micros, cost_per_conversion). - google_ads.search_terms.report: return shape is {search_term, metrics:{impressions, clicks, cost_micros, cost, conversions, ctr}} per mappers.map_search_term. Previous description invented keyword, match_type, ad_group, and conversion_value fields. Rewritten to match; clarifies that campaign_id / ad_group_id filters do not echo back in the output rows. - search_console.sitemaps.submit: actual return is {"status": "submitted", "sitemap": feedpath} per SearchConsoleApiClient.submit_sitemap, not an empty object. Description corrected. HIGH - google_ads.schedule_targeting.list: end_hour range is 0-24 (not 1-24; 24 denotes end-of-day per Google Ads). start_minute / end_minute are string forms of the MinuteOfHour enum ('ZERO' / 'FIFTEEN' / 'THIRTY' / 'FORTY_FIVE') per _extensions_targeting.list_schedule_targeting, not integers. bid_modifier is float-or-null. All now disclosed. MEDIUM - search_console.sitemaps.submit: softened the "idempotent" overclaim to "safe to call repeatedly; re-submitting re-queues a crawl without creating a duplicate entry". - google_ads.landing_page.analyze: added truncation caps per lp_analyzer.py (features <= 30, structured_data <= 5 JSON-LD blocks, max_redirects = 5, User-Agent 'MarketingAgent/1.0') and expanded the SSRF disclosure to cover link-local / reserved ranges and the post-redirect re-validation. Verified: ast.parse OK, ruff clean, black unchanged, pytest 1774 passed.
8 tasks
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.
Summary
Rewrite MCP tool descriptions for the remaining ~51 Meta Ads tools that PR #43 did not cover, applying the same TDQS template from
docs/tdqs-style-guide.md.Why
TDQS on the current state (post-PR #43):
meta_ads.creatives.listat 2.1/5 - a C-grade laggardMost of the lowest-scoring tools live in the Meta Ads ecosystem. This PR rewrites every remaining Meta Ads tool so the TDQS re-score focuses on the most severe laggards first.
Scope
_tools_meta_ads_creatives.py_tools_meta_ads_audiences.py_tools_meta_ads_insights.py_tools_meta_ads_catalog.py_tools_meta_ads_conversions.py_tools_meta_ads_leads.py_tools_meta_ads_other.pyApproach
Every rewritten tool covers the six TDQS dimensions:
creatives.createvscreate_dynamicvscreate_carouselaccount_id=act_XXXX;image_hashvsimage_urlmutual exclusion;limitdefaults; ISO 4217 currency codes for CAPI)Test plan
ast.parse) on all 7 rewritten filesblack --checkapplieddocker buildsucceedsdocker run+ MCPinitialize+tools/list- all 173 tools still loadmeta_ads.creatives.*family avg lifts from 2.88 toward B bandNon-goals
TOOLS: list[Tool]public interface unchanged