Skip to main content
Glama
github-fetcher

github-fetcher

by KurvCygnus

GitHub trending approximation

github_trending
Read-onlyIdempotent

Approximate GitHub trends by listing rising and active repositories and tracking star gains across cached search snapshots, with language, window, and star-floor filters.

Instructions

Compute a trending approximation from GitHub search, NOT GitHub's trending page: the rising lens lists repositories created inside the window above the star floor and the active lens lists repositories pushed inside the window, both sorted by stars. Star gains are not observable from search alone; every observation is snapshotted under the cache directory, and repeated calls with the same lens, language, and window gain stars_gained against the previous snapshot, so deltas accumulate across calls into real velocity. Costs 2 search calls against the 30 requests/minute search quota. Returns {window, language, lenses{rising, active}, rising_incomplete_results, active_incomplete_results, source}.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "github_trending"
  }
}

Input Schema

NameRequiredDescriptionDefault
freshNoBypass the local cache
limitNoRows per lens, 1-30, default 15
windowNoLookback window for both lenses; daily is 1 day, weekly 7, monthly 30, default weekly
languageNoRestrict both lenses to one language qualifier, like rust or typescript
min_starsNoStar floor for both lenses (stars:>N), default 100

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.5.0

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations only declare read/ idempotent/ open-world safety, while the description adds genuinely non-obvious behavior: search alone cannot observe star gains, observations are persisted under a cache directory, and deltas only emerge on repeat calls. It also discloses quota cost and backfills the return shape (window, language, lenses, *_incomplete_results, source). One tension worth noting: repeated identical calls are described as yielding changing deltas, which sits awkwardly beside idempotentHint=true, though the write is local cache only rather than remote state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core distinction and the two lens definitions before any caveats, and every sentence carries information (lens semantics, cache behavior, quota, return shape). It is a single dense block joined by semicolons, which is efficient but slightly harder to scan than separated clauses.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description enumerates the return object's fields, and it covers the quota budget, cache lifecycle, snapshot/delta mechanics and the incomplete-results flags. For a 5-optional-parameter read tool with that complexity, nothing an agent needs in order to call or interpret it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot: window, language and min_stars apply to *both* lenses, and the cache key is the combination of lens, language and window — which explains why deltas only accumulate under identical parameters. That is real guidance beyond the field documentation, though per-parameter formats are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause names the specific action and data source ('compute a trending approximation from GitHub search') and explicitly negates the confusion case ('NOT GitHub's trending page'). It then defines the two lenses (rising = created inside the window above the star floor, active = pushed inside the window) so an agent knows exactly what rows appear. This is distinguishable at a glance from the sibling github_search_repos, which does not rank by star velocity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear usage pattern: repeated calls with the same lens, language and window accumulate stars_gained into velocity, and `fresh` bypasses the cache. It also states a hard operating constraint (2 search calls against the 30 requests/minute quota). What it lacks is any explicit statement of when to prefer a sibling such as github_search_repos or github_stargazers instead of this approximation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.