Agent-first resource directory for AI agents: protocols, security, RAG, memory, evals, and more.
Scored across 14 tools
Most tools target a distinct resource, but several boundaries are fuzzy: `search` (all content) vs `search_resources` (corpus only) use nearly identical ranking language and will be easy to misselect, and `get_corpus` vs `get_full_corpus` differ only by entitlement. The trio `get_pricing` / `get_payment_info` / `get_access_info` all return commercial/informational data and require reading descriptions closely to tell apart.
Almost everything follows a clean snake_case verb_noun pattern (get_resource, list_articles, check_access, get_full_corpus). The only deviation is the bare verb `search` sitting alongside `search_resources`, which breaks the otherwise predictable resource-suffixed pattern and adds to the confusion between those two.
14 tools is a reasonable scope for a read-only content/licensing API covering discovery, fetch, search and entitlement checks. A few could be consolidated (the two search tools, and arguably `get_access_info` into `get_pricing`), so it is slightly over the sweet spot but not bloated.
The read-only lifecycle is well covered: list → search → fetch for resources, articles and clusters, plus whole-corpus bulk ingest, stats/feeds, and key/pricing/payment lookups. Minor gaps exist (no direct cluster-listing or category/tag browse tool outside `get_stats`, and list pagination only documented for articles), but agents can work around them.
Verify an access key and report what it unlocks. Returns valid:true/false; when valid, the tier, when it was created, the premium slugs it unlocks, and whether it grants the gated /api/corpus.full.jsonl + get_full_corpus deliverable (corpus, corpus-annual and enterprise tiers only). Never returns the key, email, or Stripe session. Use this to confirm a freshly-purchased key works before relying on it.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | Yes | Access key to verify (cg_...) |
| Name | Required | Description |
|---|---|---|
| tier | No | |
| valid | Yes | |
| corpus_version | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new context: it never echoes the key, email, or Stripe session, and it encodes the tier-gating rule that only corpus/corpus-annual/enterprise unlock the full-corpus deliverable. It stops short of describing error or invalid-key behavior, which matters for a verification tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the verb and the return contract, with no filler. The return-field enumeration is compact and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return shape needs only a summary, which the description provides, along with privacy guarantees, the tier-gating rule, and a usage trigger. Nothing essential for correct invocation is missing for a one-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter with 100% schema description coverage, so the schema already carries the semantics including the 'cg_...' format. The description only implies the input is the key under test, which is adequate but adds nothing beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Verify an access key') and immediately says what it reports ('what it unlocks'). An agent can distinguish it from read-style siblings like get_access_info, though no sibling is named explicitly to sharpen the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete when-to-use: 'confirm a freshly-purchased key works before relying on it.' It does not address when to prefer get_access_info or get_payment_info instead, so routing guidance is incomplete but the primary trigger is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return current access and pricing information for ChangeGamer resources.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and idempotency profile is fully covered by structured data. The description contributes only the word "current," implying a live rather than cached read, and the resource scope; it says nothing about auth requirements, rate limits, or what the payload contains. With annotations doing most of the work, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler or redundancy. It is efficient, though it is arguably too terse given the routing ambiguity against its siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and no output schema, the description is the only source of information about what the response looks like, and it never explains what "access" means (entitlements? tier? permissions?) or how it relates to the pricing portion. Annotations make the call mechanically safe, but the agent still cannot predict the return shape before invoking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level detail is needed or missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ("Return") and a concrete resource ("current access and pricing information for ChangeGamer resources"), so an agent knows the general kind of data it yields. However, it does nothing to separate itself from the siblings check_access, get_pricing, and get_payment_info, which plausibly return overlapping data, leaving the agent to guess which one to call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no preconditions, and no mention of alternatives despite three siblings (check_access, get_pricing, get_payment_info) that appear to cover adjacent territory. The agent must infer the routing decision entirely on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one ChangeGamer guide (editorial article) by slug as full Markdown with its metadata header, plus a second JSON block with the canonical URL, citation/bibtex and the reference resources it builds on. Always free — never part of the paid corpus. Use list_articles or search to discover slugs.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Article slug (e.g. "rag-in-production") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial value beyond them: exact return structure (Markdown body with metadata header plus a JSON block containing canonical URL, citation/bibtex, and referenced resources) and the always-free/not-paid-corpus constraint. Error behavior is not covered, but the added behavioral detail is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose, free-status, and discovery alternative, with the core action front-loaded. No repeated or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with rich annotations and no output schema, the description supplies the missing return-value detail (Markdown body and JSON block) and the free/paid boundary. Nothing essential for correct invocation is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single slug parameter is fully documented with an example in the schema. The description only adds the phrase 'by slug', so it does not meaningfully extend parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Fetch), resource (one ChangeGamer guide / editorial article), selector (by slug), and output shape, clearly distinguishing it from discovery tools. Naming list_articles and search as separate discovery routes further sharpens its role among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs the agent to list_articles or search when it lacks a slug, which is the main ambiguity for this tool. It does not explicitly say when to use get_resource instead for non-guide resources, but the guide/editorial-article framing provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one ChangeGamer guide cluster (topic bundle) from the free editorial layer: cluster metadata, every member article as a compact row with its Markdown URL, and the pillar’s full Markdown body. Use list_articles to discover cluster ids.
| Name | Required | Description | Default |
|---|---|---|---|
| cluster_id | Yes | Cluster id, e.g. "rag-in-production" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds context they cannot carry: the data comes from the "free editorial layer" (a tier/access distinction that matters alongside check_access/get_payment_info siblings) and that the response includes a full Markdown body, implying a potentially large payload. It doesn't mention size limits or failure modes for unknown ids.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first front-loads what is returned, the second is a routing pointer. Nothing redundant with the title or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the work of describing the return shape (metadata + article rows + pillar body), which is the essential gap. Minor omissions remain around payload size and behavior for a nonexistent cluster id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
One required parameter with 100% schema description coverage including a concrete example ("rag-in-production"), so the schema already carries the semantics. The description only implies that cluster ids come from list_articles and adds no format or validity detail beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (fetch) and resource (one guide cluster / topic bundle) and enumerates the returned payload: cluster metadata, member article rows with Markdown URLs, and the pillar's full Markdown body. That detail distinguishes it from get_article and list_articles without needing to open any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use list_articles to discover cluster ids" gives an explicit prerequisite/orientation step and points at a sibling. It stops short of saying when to prefer get_article (single article) or get_corpus over this, so coverage is clear-but-not-exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the entire free corpus as one document (every free resource title, description, canonical URL, and full Markdown body) — the same content as /llms-full.txt. Premium resources appear as a stub with a purchase link, not their body. Use this to ingest everything in a single call; the response is large. Optional category returns only that category's resources (smaller result). Size without category: about 890 KB.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Only resources in this category (case-insensitive): Guide, Policy, Reference, Meta. Omit for the whole corpus. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context on top: premium entries come back as a purchase-link stub rather than a body, the response is large, and it is roughly 890 KB uncategorized.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense paragraph that front-loads what is returned, then the premium-stub caveat, then usage, then size. Efficient overall, though "the response is large" and "about 890 KB" convey the same warning twice.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-shape burden and does it: it enumerates the fields returned, explains how premium entries differ, and quantifies payload size so the agent can anticipate token cost. The only gap is the missing contrast with get_full_corpus.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already enumerates the four category values (Guide, Policy, Reference, Meta) and the omit-for-whole-corpus behavior. The description only repeats the intent ("only that category's resources, smaller result") without adding syntax or edge-case meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource: returns the entire free corpus as one document, with a concrete field list (title, description, canonical URL, Markdown body) and an explicit stub policy for premium resources. It does not, however, name or distinguish itself from the sibling get_full_corpus, leaving the agent to infer the difference between 'free corpus' and 'full corpus'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this to ingest everything in a single call" gives a clear selecting condition (bulk ingestion vs. per-item access via get_article/search), and the optional category is framed as the way to get a smaller result. There is no explicit when-not or named alternative, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the ENTIRE corpus including premium resource bodies in one document — the keyed deliverable of the Corpus/Enterprise license. Requires a Corpus-, Corpus-annual- or Enterprise-tier api_key (a Starter key unlocks premium resources but NOT the corpus file); without an entitled key a payment-required/upgrade object is returned. The free, premium-stubbed version is get_corpus. Size: about 900 KB.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | Corpus/Enterprise license key (cg_...) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description adds the parts annotations cannot: the entitlement gate, the failure behavior (a payment-required/upgrade object is returned rather than an error), and the payload size (~900 KB). That is substantive beyond structured fields; it falls short of 5 only because it says nothing about whether the response can be streamed or truncated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense and front-loaded: the core deliverable comes first, then entitlement, then fallback behavior, then size. The phrase 'the keyed deliverable of the Corpus/Enterprise license' is mild framing rather than instruction, but the rest earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still tells the agent what comes back (one document containing premium bodies), its approximate size, and the alternative success path (an upgrade object). Combined with annotation coverage, nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single api_key parameter is fully documented in the schema, so the baseline would be 3. The description goes further by tying the key to specific license tiers and by distinguishing which tier does not grant access, which is semantic meaning the schema's 'Corpus/Enterprise license key (cg_...)' string does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the ENTIRE corpus including premium resource bodies in one document') and immediately scopes it against the sibling get_corpus, which is named as the free premium-stubbed version. An agent can separate the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit selection conditions: use this when you hold a Corpus-, Corpus-annual- or Enterprise-tier key; otherwise use get_corpus. It also calls out the trap case (a Starter key unlocks premium resources but NOT the corpus file), which is exactly the kind of exclusion an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the agent payment manifest: every way to pay (HTTP 402 + Bearer key, MCP, Stripe checkout, x402, RSL per-crawl), the exact 402 retry loop, what is always free, and the recommended path per use case. Same data as /api/payment.json.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| methods | Yes | |
| recommended | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and non-destructive, so the safety profile is settled. The description adds genuine substance beyond that: it discloses the return payload's structure (all payment methods, the retry loop, what's always free, per-use-case recommendations) and notes it mirrors /api/payment.json, which lets an agent reason about freshness and content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Effectively two sentences: a front-loaded statement of purpose with an enumerated payload, then a pointer to the equivalent HTTP endpoint. Every clause carries information. It is dense but not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not owed, and with zero parameters there is no input surface to cover. What remains missing is sibling differentiation against get_pricing and check_access, the only thing an agent could still get wrong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly says nothing about inputs rather than inventing any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the agent payment manifest') and enumerates the concrete contents: payment methods, the 402 retry loop, free items, recommended paths. An agent knows exactly what comes back. However, it does not distinguish itself from siblings get_pricing, check_access, or get_access_info, which cover overlapping payment/access territory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: mentioning 'the exact 402 retry loop' signals you call this when you need to know how to pay, but there is no explicit 'use this when / use X instead' guidance. With get_pricing and check_access as siblings, the absence of routing guidance is a real gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full paid-offer catalog: every tier with price, currency, interval, checkout URL, what it unlocks, deliverables, and license grant — plus the free layer and premium slug list. Same data as /api/pricing.json.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| offers | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the call is unfiltered (whole catalog, plus free layer and slug list) and it mirrors /api/pricing.json, which lets an agent reason about freshness and parity with a known endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the catalog scope and followed by the field list and the endpoint equivalence. The field enumeration overlaps somewhat with the existing output schema, which is the only minor waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present the description needn't document return shapes, and it gives enough to call correctly: no inputs, whole catalog, same as /api/pricing.json. Only the relationship to sibling access/payment tools is left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate and it correctly presents the call as parameter-free.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource plus scope ('Return the full paid-offer catalog') and enumerates the contents, so an agent knows exactly what this returns. It does not differentiate itself by name from adjacent siblings like get_payment_info or check_access, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent needing tier/price/license data would pick this. There is no explicit when-to-use, when-not, or pointer to a related sibling such as check_access for entitlement questions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a ChangeGamer resource by slug. Free resources return full metadata, the Markdown body, cited source URLs and a ready-made citation/bibtex. Premium resources require a valid api_key; without one a payment-required object is returned. An unknown slug returns did_you_mean suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Resource slug (e.g. "getting-started") | |
| api_key | No | Access key for premium resources |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint, yet the description still adds substantial behavioral context: what a free result contains (metadata, Markdown body, source URLs, citation/bibtex), that premium results require a valid api_key, that a payment-required object is returned otherwise, and that unknown slugs yield did_you_mean suggestions. These are auth, success-shape and failure-mode disclosures an agent cannot derive from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action and followed by the return/auth/error variants. Every clause carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so fully: free vs premium response shapes and the unknown-slug fallback. Nothing needed to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented. The description adds only that api_key gates premium content and that slug identifies a resource, which is marginal beyond the schema's own wording; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a ChangeGamer resource by slug'), which distinguishes it from siblings like get_article, list_resources and search_resources. An agent knows exactly what comes back without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied ('by slug' suggests a slug must come from search_resources or list_resources) but never stated explicitly. The description also names no alternative for when a slug is unknown beyond the did_you_mean hint; there is no explicit routing advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return corpus stats: total/free/premium counts, per-category counts, tag count, newest/oldest update dates, the 10 most recently updated resources, feed URLs — plus an editorial block (guide count, words, newest publish) merged at runtime from the static articles index. A small freshness/size signal to poll before deciding whether to re-ingest.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| total | Yes | |
| premium | Yes | |
| corpus_version | Yes | |
| newest_updated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is pre-covered. The description adds genuinely new behavioral context: the editorial block is 'merged at runtime from the static articles index' and the tool is cheap enough to 'poll'. It does not quantify cost or latency, but that is a minor gap given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with 'Return corpus stats:' and stays to roughly two sentences, but the long enumerations of counts and dates substantially duplicate the output schema, which the agent already has. Those tokens are largely redundant, though the final freshness/polling sentence does earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool that already ships an output schema and rich annotations, this is essentially complete: it conveys nature, provenance of the merged editorial block, and intended use. The only loose end is the unexplained 'static articles index' merge, which hints at possible staleness without saying how fresh the data is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4 per the rubric. Nothing about argument semantics needs explaining, and the description correctly avoids inventing any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return corpus stats') and then enumerates exactly what the payload contains (counts, dates, recent resources, feed URLs, editorial block). This clearly separates it from content-returning siblings like get_corpus, get_full_corpus, and search_resources without the agent needing to open a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The closing clause gives a concrete usage context: 'a small freshness/size signal to poll before deciding whether to re-ingest.' That tells the agent when this tool is the right call. It stops short of naming explicit alternatives or when-not-to-use cases, so it is a strong 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ChangeGamer editorial guides (always free, separate from the licensable corpus): compact rows (slug, title, cluster, kind, order, description, updated, Markdown URL), one page at a time, plus the cluster list. cluster narrows to one topic; full: true returns the complete index with search intents, takeaways and variant URLs. No body content — fetch bodies with get_article. Size with full: true: about 710 KB.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | true = the complete /api/articles.json index; other arguments ignored. | |
| limit | No | Rows per page (default 30). | |
| offset | No | Rows to skip (default 0); pass next_offset. | |
| cluster | No | Only this cluster id (see `clusters`). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent safety, and the description adds genuinely new operational context: results are paginated one page at a time, full:true returns ~710 KB so the agent can judge cost, and full:true ignores other arguments. It also clarifies the licensing boundary that annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: what it lists, how to narrow/expand it, and the body-content redirect. The payload-size warning is placed where it matters and no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by listing returned row fields and noting the cluster list is included. Combined with pagination and size disclosure, an agent has everything needed to call this correctly on the first try.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3; the description still adds value by describing what `full: true` actually returns (search intents, takeaways, variant URLs) rather than just its boolean meaning. `limit`/`offset` are left entirely to the schema, which is acceptable given full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List ChangeGamer editorial guides") and immediately scopes it ("always free, separate from the licensable corpus"), which distinguishes it from get_corpus/get_full_corpus siblings. It also enumerates the exact row fields returned, so the agent knows precisely what this yields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes body-content needs to get_article ("No body content — fetch bodies with get_article") and explains the cluster-narrowing and full-index modes. It stops short of contrasting with the search sibling for locating a specific guide, but the core use/avoid guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all ChangeGamer resources with metadata and absolute URLs. Returns slug, title, description, category, tags, updated date, premium flag, and HTML/Markdown/JSON variant URLs. No body content. Optional category and premium filters narrow the list; without them every resource is returned.
| Name | Required | Description | Default |
|---|---|---|---|
| premium | No | true = only premium resources, false = only free ones. | |
| category | No | Only resources in this category (case-insensitive): Guide, Policy, Reference, Meta. |
| Name | Required | Description |
|---|---|---|
| resources | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real context: full field inventory, absolute URLs, URL variants per format, and the explicit "No body content" limitation. It stops short of noting result size or pagination when no filter is applied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: identity, return shape, then filter behavior. Front-loaded with the core operation, zero filler, and the "No body content" caveat sits before the parameter note where it matters most.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values needn't be spelled out, and annotations cover the safety profile. A 2-param read-only list tool is well served here; the only gap is no guidance on unfiltered result volume, which is a plausible concern given the description promises every resource when unfiltered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both params carry their own enum-like value lists, so the baseline is 3. The description contributes only the default behavior ("without them every resource is returned"), which is a marginal addition over the schema's own definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ("List all ChangeGamer resources") plus an explicit inventory of returned fields and the boundary "No body content." It does not name the sibling it is distinguished from (search_resources, get_resource), so the agent must infer the split, but the purpose itself is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Optional `category` and `premium` filters narrow the list; without them every resource is returned" covers the filtering decision but says nothing about when to prefer this over search_resources or get_resource, or when not to call it (e.g. large unfiltered result sets). Usage is implied, not directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keyword search across ALL ChangeGamer content (resources and editorial guides), ranked like the site search: every word must match; title hits weigh most, then tags, category, description. Returns ranked rows with type, slug, title, description, premium flag, .md and HTML URLs (no body content). Use get_resource/get_article to fetch winners.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query — one or more keywords; every word must match | |
| type | No | Only resources or only guides (articles). | |
| limit | No | Max results (default 10) |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| query | Yes | |
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral detail: AND-matching semantics, the ranking order (title > tags > category > description), and the fact that bodies are excluded. Missing only edge-case behavior such as empty-result handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with scope, then ranking, then return shape and next step. Dense but nearly every clause carries information; the ranking-weight list is the only part bordering on excess given the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still names the returned fields and flags that bodies are absent, which is beyond requirement. Combined with matching/ranking semantics and a follow-up route, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter is documented in the schema, so the baseline is 3. The description adds the ranking/matching model, but repeats 'every word must match' which q's schema text already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Keyword search across ALL ChangeGamer content') and clarifies scope as resources plus editorial guides, which separates it from get_resource/get_article. It does not, however, distinguish itself from the very similar sibling search_resources, leaving the agent to infer which to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent onward: 'Use get_resource/get_article to fetch winners', establishing this as a discovery tool rather than a fetcher. It gives no guidance on when to prefer it over the sibling search_resources or list_resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the ChangeGamer corpus by keyword. Every word must match the title, tags, category, description or (as a last resort) the body; results rank title > tags > category > description > body, the same order as the site search. Returns metadata plus HTML/Markdown/JSON URLs (no body content). Use this to find resources before fetching them with get_resource.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default 10). | |
| query | Yes | Search keywords, e.g. "retrieval augmented generation" or "mcp auth" |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| query | Yes | |
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing the AND-matching rule (every word must match), the field-priority ranking order, and the fact that results contain only metadata and HTML/Markdown/JSON URLs with no body content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no filler, and the matching/ranking rules are front-loaded before the return-format and routing guidance. Every clause carries information an agent would otherwise have to guess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers search semantics, ranking, failure mode of body-only matches, return payload shape, and the natural next tool. With annotations and an output schema already present, nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: it explains that all query terms must match and where they are matched, which is more than the schema's simple example string conveys. The limit parameter is left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) and resource (ChangeGamer corpus) plus the exact matching rules across title, tags, category, description and body. It clearly separates itself from get_resource by describing itself as the discovery step that returns metadata/URLs rather than content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this to find resources before fetching them with get_resource" gives an explicit when-to-use and names the follow-up tool. It does not, however, distinguish itself from the sibling tool named `search`, leaving an ambiguity an agent must resolve on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_access2 fields changedInput schema / properties / api_key / maxLengthAdded value: +256Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": true,
+ "properties": {
+ "corpus_version": {
+ "type": "string"
+ },
+ "tier": {
+ "type": "string"
+ },
+ "valid": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "valid",
+ "corpus_version"
+ ],
+ "type": "object"
+}get_article1 field changedInput schema / properties / slug / maxLengthAdded value: +200get_cluster1 field changedInput schema / properties / cluster_id / maxLengthAdded value: +200get_corpus1 field changedInput schema / properties / category / maxLengthAdded value: +200get_full_corpus1 field changedInput schema / properties / api_key / maxLengthAdded value: +256get_payment_info1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": true,
+ "properties": {
+ "methods": {
+ "items": {
+ "additionalProperties": true,
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "status"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "recommended": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "methods",
+ "recommended"
+ ],
+ "type": "object"
+}get_pricing1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": true,
+ "properties": {
+ "offers": {
+ "items": {
+ "additionalProperties": true,
+ "properties": {
+ "checkout_url": {
+ "type": "string"
+ },
+ "currency": {
+ "type": "string"
+ },
+ "id": {
+ "type": "string"
+ },
+ "price": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "id",
+ "price",
+ "currency",
+ "checkout_url"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "offers"
+ ],
+ "type": "object"
+}get_resource2 fields changedInput schema / properties / api_key / maxLengthAdded value: +256Input schema / properties / slug / maxLengthAdded value: +200get_stats1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": true,
+ "properties": {
+ "corpus_version": {
+ "type": "string"
+ },
+ "newest_updated": {
+ "type": "string"
+ },
+ "premium": {
+ "type": "number"
+ },
+ "total": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "total",
+ "premium",
+ "corpus_version",
+ "newest_updated"
+ ],
+ "type": "object"
+}list_articles5 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / clusterAdded value: +{
+ "description": "Only this cluster id (see `clusters`).",
+ "maxLength": 200,
+ "type": "string"
+}Input schema / properties / fullAdded value: +{
+ "description": "true = the complete /api/articles.json index; other arguments ignored.",
+ "type": "boolean"
+}Input schema / properties / limitAdded value: +{
+ "description": "Rows per page (default 30).",
+ "maximum": 50,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "description": "Rows to skip (default 0); pass next_offset.",
+ "minimum": 0,
+ "type": "integer"
+}list_resources4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / categoryAdded value: +{
+ "description": "Only resources in this category (case-insensitive): Guide, Policy, Reference, Meta.",
+ "maxLength": 200,
+ "type": "string"
+}Input schema / properties / premiumAdded value: +{
+ "description": "true = only premium resources, false = only free ones.",
+ "type": "boolean"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": true,
+ "properties": {
+ "resources": {
+ "items": {
+ "additionalProperties": true,
+ "properties": {
+ "category": {
+ "type": "string"
+ },
+ "markdown": {
+ "type": "string"
+ },
+ "premium": {
+ "type": "boolean"
+ },
+ "slug": {
+ "type": "string"
+ },
+ "title": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "slug",
+ "title",
+ "category",
+ "premium",
+ "markdown"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "resources"
+ ],
+ "type": "object"
+}search4 fields changedInput schema / properties / q / descriptionPrevious value: -"Search query — one or more keywords"New value: +"Search query — one or more keywords; every word must match"Input schema / properties / q / maxLengthAdded value: +500Input schema / properties / typeAdded value: +{
+ "description": "Only resources or only guides (articles).",
+ "enum": [
+ "resource",
+ "article"
+ ],
+ "type": "string"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": true,
+ "properties": {
+ "count": {
+ "type": "integer"
+ },
+ "query": {
+ "type": "string"
+ },
+ "results": {
+ "items": {
+ "additionalProperties": true,
+ "properties": {
+ "premium": {
+ "type": "boolean"
+ },
+ "score": {
+ "type": "number"
+ },
+ "slug": {
+ "type": "string"
+ },
+ "title": {
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "resource",
+ "article"
+ ],
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "score",
+ "type",
+ "slug",
+ "title",
+ "premium",
+ "url"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "query",
+ "count",
+ "results"
+ ],
+ "type": "object"
+}search_resources2 fields changedInput schema / properties / query / maxLengthAdded value: +500Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": true,
+ "properties": {
+ "count": {
+ "type": "integer"
+ },
+ "query": {
+ "type": "string"
+ },
+ "results": {
+ "items": {
+ "additionalProperties": true,
+ "properties": {
+ "markdown": {
+ "type": "string"
+ },
+ "premium": {
+ "type": "boolean"
+ },
+ "relevance": {
+ "type": "number"
+ },
+ "slug": {
+ "type": "string"
+ },
+ "title": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "slug",
+ "title",
+ "premium",
+ "relevance",
+ "markdown"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "query",
+ "count",
+ "results"
+ ],
+ "type": "object"
+}get_corpus2 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / categoryAdded value: +{
+ "description": "Only resources in this category (case-insensitive): Guide, Policy, Reference, Meta. Omit for the whole corpus.",
+ "type": "string"
+}get_clustersearchget_articlelist_articlescheck_accessget_full_corpusget_payment_infoget_pricingget_statsget_corpussearch_resourcesget_access_infoget_resourcelist_resources
Add one secure layer between your agents and this server.