Renamed to FactReason. Now published as io.github.factreason/factreason — please use that entry.
Compare two versions of a third-party API and return breaking changes, including removed endpoints, parameter type changes, removed request body fields, and migration guides. Use factreason_package_upgrade_advisory for npm or PyPI packages.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | Third-party API service, e.g. "Stripe" or "OpenAI" | |
| toVersion | No | Optional exact version being evaluated | |
| fromVersion | No | Optional exact version currently targeted |
| Name | Required | Description |
|---|---|---|
| found | No | |
| billed | No | |
| changes | No | |
| meaning | No | |
| message | No | |
| service | No | |
| suggestion | No | |
| changeCount | No | |
| alternatives | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only, idempotent, and non-destructive, so the description does not need to restate those. It adds useful context about what kinds of breaking changes are reported and that migration guides are included, while avoiding any contradiction with 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?
The description is two sentences with no filler. The core purpose and output categories are front-loaded, and the alternative-tool guidance is a useful second sentence.
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?
The description is largely complete given the annotations and output schema. The main gap is that both version parameters are optional in the schema, but the description says 'compare two versions' without explaining what happens when only service is provided or how defaults are resolved.
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?
All three parameters are already fully described in the schema with 100% coverage, so the baseline applies. The description's 'compare two versions' phrasing aligns with fromVersion and toVersion but does not add extra semantic detail 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?
The description clearly states what the tool does: compare two versions of a third-party API and return breaking changes, with specific examples of the output (removed endpoints, parameter type changes, removed request body fields, migration guides). It also distinguishes itself from the sibling tool factreason_package_upgrade_advisory by explicitly naming the alternative context.
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 description provides an explicit routing rule: use factreason_package_upgrade_advisory for npm or PyPI packages, implying this tool is for other third-party APIs. This gives the agent clear guidance on when to select this tool versus the named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search exact request and response schemas for third-party API endpoints. Pass service alone to list its indexed endpoints, add query to narrow by path or operation, or use query alone across services; returns matches or nearest services. Uses metered access and does not modify source data. Prefer factreason_integration_brief for one callable request.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional endpoint path or operation, e.g. "payment_intents" | |
| service | No | Optional service filter, e.g. "Stripe" |
| Name | Required | Description |
|---|---|---|
| hint | No | |
| found | No | |
| message | No | |
| results | No | |
| totalMatched | No | |
| nearestServices | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is known. The description adds that it 'Uses metered access' and 'does not modify source data,' which clarifies operational behavior. It could mention pagination or result format, but with output schema present, the description adds sufficient value above annotations to warrant a 4.
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?
The description is three sentences, each adding distinct value: purpose, usage patterns, and an alternative tool reference. It is concise and front-loaded, with no redundant 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?
Given the tool's simplicity (2 optional params) and rich annotations and output schema, the description covers purpose, usage modes, and behavioral notes. It also provides a pointer to a sibling tool. No critical gaps.
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% (both params described). The description adds semantic nuance: 'Pass service alone to list its indexed endpoints, add query to narrow by path or operation, or use query alone across services' explains how params combine, which goes beyond schema descriptions. This justifies a slight upgrade from baseline 3 to 4.
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?
The description clearly states the tool searches for exact request and response schemas for third-party API endpoints, using a specific verb ('Search') and resource ('schemas'). It distinguishes from siblings like factreason_integration_brief by explicitly naming an alternative, making the scope 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?
It provides explicit usage patterns: 'Pass service alone to list its indexed endpoints, add query to narrow by path or operation, or use query alone across services' and recommends 'Prefer factreason_integration_brief for one callable request.' This gives clear when-to-use and when-not-to-use guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get publisher-declared authentication schemes, scopes, rate-limit headers, and error codes for one third-party API. Returns a structured playbook or nearest service suggestions, and marks undocumented details as unstated rather than guessing. Uses metered access. Prefer factreason_integration_brief when assembling a complete API call.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | Third-party API service, e.g. "Stripe", "Twilio", or "Cloudflare" |
| Name | Required | Description |
|---|---|---|
| found | No | |
| compact | No | |
| message | No | |
| playbook | No | |
| nearestServices | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. Description adds behavioral details: returns structured playbook or suggestions, marks unstated fields, and uses metered access. This goes beyond 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 concise sentences, front-loaded with action and outcome, then details, then alternative. No wasted words.
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?
Given output schema exists and annotations cover safety, the description fully explains purpose, behavior, and alternatives. Missing details (return format) are covered by output schema.
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 has 100% coverage with description and examples. Description adds nothing about the parameter beyond 'one third-party API', which is implicit. Baseline 3 is appropriate.
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?
Description names specific resource ('publisher-declared authentication schemes, scopes, rate-limit headers, and error codes') and scope ('one third-party API'), clearly distinguishing from siblings by pointing to factreason_integration_brief.
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 says to prefer factreason_integration_brief for complete API calls, indicating when not to use this tool. Also notes metered access, giving cost-related guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up electronics component pin assignments, voltage range, package, and alternatives. Pass exact partNumber for one component or query for a capability search; partNumber takes precedence if both are supplied. For exact lookups, set responseFormat="compact" for tokenizer-measured context savings; the backward-compatible default is "full". Uses metered access and returns matches or suggestions. Confirm critical values against the manufacturer datasheet.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Free-text capability search, e.g. "3.3V ARM MCU with SPI" | |
| partNumber | No | Exact part number, e.g. "STM32F401RE" | |
| responseFormat | No | Use compact for an exact part lookup; full preserves the legacy data response | full |
| Name | Required | Description |
|---|---|---|
| data | No | |
| hint | No | |
| found | No | |
| compact | No | |
| message | No | |
| results | No | |
| partNumber | No | |
| provenance | No | |
| qualityScore | No | |
| tokenMetrics | No | |
| totalMatched | No | |
| nearestMatches | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly/idempotent/destructive status, and the description adds valuable behavior beyond that: metered access, returns matches or suggestions, and a caution to confirm values against the manufacturer datasheet. This adds useful context about usage cost and data reliability, though it does not detail edge-case behavior such as empty or invalid results.
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?
Four sentences are present, and each contributes essential information: purpose, input modes/precedence, response-format guidance, and metered/caveat context. The first sentence is immediately informative, and there is no filler, redundancy, or unnecessary escalation.
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 full annotations, 100% schema parameter coverage, and an output schema present, the description is sufficiently complete: it specifies input choices, precedence, response format trade-offs, metered access behavior, and a critical accuracy caveat. An agent has enough context to select and invoke the tool 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?
The schema already describes all parameters, but the description adds meaningful semantics by defining precedence when partNumber and query are both supplied and by explaining when responseFormat should be 'compact' versus the default 'full'. This goes beyond the bare schema descriptions and genuinely helps correct invocation.
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?
The description uses a specific verb ('Look up') with a concrete resource ('electronics component pin assignments, voltage range, package, alternatives'), making the tool's purpose immediately clear. It also distinguishes this tool from its API-management siblings by focusing on component data rather than schemas, auth, or breaking changes.
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 description gives explicit usage guidance: pass an exact partNumber for one component or use a query for capability search, and it states that partNumber takes precedence when both are supplied. It also advises when to use responseFormat='compact', though it does not explicitly identify converse cases or alternative tools for when this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a FactReason API key for yourself, instantly, with no human, no signup and no card. Returns a key carrying one-off trial credit that you can spend immediately on any tool. CALL THIS FIRST if you have no key, or as soon as any FactReason tool returns HTTP 402 Payment Required — then retry the original call with the key. The tool is free and is never metered. Supplying an email is optional and only affects whether trial credit is granted; a key is always issued either way.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Optional contact address for the key owner. Improves the chance of receiving trial credit and lets the operator reach you about corrections. Never send a human's address without their agreement. |
| Name | Required | Description |
|---|---|---|
| note | No | |
| error | No | |
| apiKey | No | |
| created | No | |
| howToUse | No | |
| topupUrl | No | |
| trialGranted | No | |
| trialCreditUsd | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (all false), the description reveals important behavior: instant issuance, no human/signup/card, returns a key with one-off trial credit, free and never metered, and email is optional but a key is always issued either way. This is substantial context that annotations do not provide.
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?
Four sentences, each earning its place: the main action, the output and credit, the critical usage instruction, and the email caveat. Information is front-loaded and no filler is present.
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?
The tool is simple (one optional parameter, output schema exists), and the description covers prerequisites (no key), error condition (HTTP 402), key characteristics (trial credit, free), and email behavior. This is complete for an agent to invoke 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 description coverage is 100%, which gives a baseline of 3. The description adds a clear semantic about the email parameter: it 'only affects whether trial credit is granted; a key is always issued either way.' This goes beyond the schema's phrasing and clarifies the consequence of omission, warranting a 4.
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?
The description opens with a specific verb and resource: 'Get a FactReason API key for yourself.' It clearly distinguishes this tool from siblings (e.g., factreason_create_topup_link) by framing it as the key acquisition tool with no human, no signup, and no card.
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?
Provides explicit, conditional usage guidance: 'CALL THIS FIRST if you have no key, or as soon as any FactReason tool returns HTTP 402 Payment Required — then retry the original call with the key.' This tells the agent exactly when to invoke this tool versus other actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Stripe Checkout URL for adding prepaid credit to the calling Bearer API key. This creates an external checkout session but does not charge a card. You CANNOT COMPLETE THE PAYMENT YOURSELF, so return the URL to a human, and credit is applied only after they complete payment. Use after HTTP 402 or when balance is low; the tool itself is not metered.
| Name | Required | Description | Default |
|---|---|---|---|
| amountUsd | Yes | Credit amount in USD; common blocks are 10, 50, and 200 |
| Name | Required | Description |
|---|---|---|
| error | No | |
| created | No | |
| amountUsd | No | |
| balanceUrl | No | |
| checkoutUrl | No | |
| createKeyUrl | No | |
| instructions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: it creates an external checkout session but does not charge a card, and credit is applied only after the human completes payment. It also notes that the tool is not metered. While annotations indicate readOnlyHint=false (so it's not read-only), the description adds important context about the external session and the need for human action, which goes beyond 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?
The description is concise and well-structured. It front-loads the core purpose, then explains the limitation (cannot complete payment), and finally provides usage context. Every sentence adds value, and the description is appropriately sized for the tool's complexity.
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?
Given the tool's simplicity (one parameter, no nested objects) and the presence of an output schema, the description is complete. It covers the purpose, usage context, behavioral limitations, and the need for human involvement. The output schema likely describes the returned URL, so the description doesn't need to explain return values. This is a well-rounded description.
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 schema already provides a description for the single parameter 'amountUsd' with common blocks (10, 50, 200). The description adds context by explaining that the amount is for prepaid credit, but it doesn't add much beyond the schema. Since schema coverage is 100% and the parameter is well-documented, a score of 4 is appropriate, as the description reinforces the purpose but doesn't introduce new semantics.
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?
The description clearly states the tool's purpose: 'Create a Stripe Checkout URL for adding prepaid credit to the calling Bearer API key.' It specifies the verb (create), the resource (top-up link), and the mechanism (Stripe Checkout URL). It also distinguishes itself from siblings by focusing on the top-up link creation, which is unique among the listed tools.
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 description provides explicit usage guidance: 'Use after HTTP 402 or when balance is low; the tool itself is not metered.' It also clarifies that the tool cannot complete the payment and the URL must be returned to a human, which is a clear when-to-use and when-not-to-use instruction. This is excellent guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan publisher specifications for deprecated endpoints or parameters, sunset dates, and replacement operations. Omit filters for the catalogue-wide view, pass service to limit one API, and add endpoints to check selected paths. Uses metered access when findings exist. Use factreason_api_breaking_changes for broader version-to-version changes.
| Name | Required | Description | Default |
|---|---|---|---|
| service | No | Optional service filter, e.g. "Stripe" or "Twilio" | |
| endpoints | No | Optional endpoint paths to check within the selected service |
| Name | Required | Description |
|---|---|---|
| count | No | |
| found | No | |
| message | No | |
| results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is disclosed. The description adds the useful behavioral note 'Uses metered access when findings exist,' which is not present in the annotations. A touch more detail about return format would push this higher, but the bar is met.
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, each earning its place: the first states the purpose, the second gives usage instructions, and the third points to an alternative tool. No redundancy, perfectly sized.
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 read-only scan tool with 0 required parameters and an output schema, the description covers the core behavior (deprecations, sunset dates, replacements), filter usage, and the closest alternative. The only minor gap is what returns look like, but the output schema presumably covers that, so this is sufficiently complete.
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% with both parameters well described. The description adds operational semantics beyond the schema: 'Omit filters for the catalogue-wide view, pass service to limit one API' and 'add endpoints to check selected paths,' which helps an agent reason about parameter combination rather than just individual fields.
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?
The description starts with a specific verb and resource: 'Scan publisher specifications for deprecated endpoints or parameters, sunset dates, and replacement operations.' It clearly states what the tool does and what it finds, and differentiates from the sibling 'factreason_api_breaking_changes' by naming it explicitly.
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?
Explicit guidance is given: 'Omit filters for the catalogue-wide view, pass service to limit one API, and add endpoints to check selected paths.' It also tells the agent when NOT to use this tool and what to use instead: 'Use factreason_api_breaking_changes for broader version-to-version changes.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find third-party APIs for a capability when the provider is unknown. Supply a concise capability such as "sms" or "manage DNS"; returns ranked services, example endpoints, and a next step. Uses metered access. When the provider is already known, call factreason_integration_brief instead.
| Name | Required | Description | Default |
|---|---|---|---|
| capability | Yes | Capability to search for, e.g. "send an SMS" or "charge a card" |
| Name | Required | Description |
|---|---|---|
| hint | No | |
| count | No | |
| found | No | |
| billed | No | |
| message | No | |
| results | No | |
| nextStep | No | |
| capability | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool safe and non-destructive. The description adds behavioral context beyond annotations, including "Uses metered access" and the return shape of "ranked services, example endpoints, and a next step." No contradiction with annotations was found.
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?
The description is three focused, front-loaded sentences with no filler. Each sentence earns its place: what it does, what to supply, what it returns, metered access caveat, and sibling alternative.
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 single-parameter discovery tool with an output schema and good annotations, the description is complete. It covers the trigger condition, input style, output contents, cost/access trait, and the key alternative sibling 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?
The schema already covers the single capability parameter at 100%, so the baseline is 3. The description adds value by specifying the expected concise format and giving contrasting examples such as "sms" and "manage DNS," which goes beyond the schema's examples.
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?
The description uses a specific verb and resource: "Find third-party APIs for a capability when the provider is unknown." It clearly distinguishes itself from the sibling factreason_integration_brief by explicitly stating when that sibling should be used instead.
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 description states the exact condition for use (provider unknown), gives an example capability format, and explicitly names the alternative: "When the provider is already known, call factreason_integration_brief instead." This is clear when-to-use vs. when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compile one callable third-party API brief: base URL, auth scheme, required parameters and types, request body, and documented response codes. Service is required and endpoint optionally narrows the operation. Set responseFormat="compact" for tokenizer-measured context savings; the backward-compatible default returns the full brief plus compact form. Uses metered access. Prefer factreason_api_schema when exploring multiple endpoints.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | Third-party API service, e.g. "Stripe" or "Twilio" | |
| endpoint | No | Optional path or operation fragment used to select one call | |
| responseFormat | No | Use compact for the callable facts only; full preserves the legacy brief response | full |
| Name | Required | Description |
|---|---|---|
| hint | No | |
| brief | No | |
| found | No | |
| billed | No | |
| compact | No | |
| message | No | |
| service | No | |
| tokenMetrics | No | |
| nearestServices | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool's safety is known. The description adds valuable context beyond that: it mentions 'Uses metered access' (cost implication) and explains the responseFormat behavior (compact vs. full and backward compatibility). No contradictions with 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 sentences, front-loaded with the primary action and deliverables. Every sentence adds information: the first defines the output, the second explains required/optional parameters, the third covers formatting options and alternatives. No fluff or repetition.
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?
Given the tool's moderate complexity (3 params, output schema present, rich annotations), the description fully addresses usage, alternatives, behavior, and constraints. It even covers cost implications (metered access) and backward compatibility, making it self-sufficient for agent decision-making.
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 each parameter has a useful description. The description adds meaning by explaining the relationship between service and endpoint ('Service is required and endpoint optionally narrows the operation') and clarifies the responseFormat default behavior ('backward-compatible default returns the full brief plus compact form'). This enriches the schema without redundancy.
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?
The description opens with a specific verb and resource: 'Compile one callable third-party API brief,' clearly listing the included elements (base URL, auth scheme, parameters, etc.). It distinguishes itself from sibling factreason_api_schema by explicitly stating that tool is for exploring multiple endpoints, while this one is for a single 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?
Provides explicit guidance: 'Prefer factreason_api_schema when exploring multiple endpoints' names the alternative tool and the condition under which to use it. Also explains the optional endpoint parameter narrows the operation, clarifying common usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two exact published npm or PyPI versions and return publisher-declared registry metadata changes, including yanks, exports, module format, runtime floors, peers, and licences, with before/after evidence. Set responseFormat="compact" for tokenizer-measured context savings; the backward-compatible default is "full". This is a read-only metered lookup; misses are never billed and every API key carries one-off trial credit. Use it for package metadata; use factreason_api_breaking_changes for a third-party HTTP API, and consult changelogs for behavioural changes.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Exact target version, e.g. "5.0.0" | |
| from | Yes | Exact currently installed version, e.g. "4.1.2" | |
| name | Yes | Exact package name, e.g. "chalk" or "urllib3" | |
| registry | Yes | Registry containing both package versions | |
| responseFormat | No | Use compact to remove repeated prose and fields while retaining evidence; full preserves the legacy response contract | full |
| Name | Required | Description |
|---|---|---|
| found | No | |
| scope | No | |
| billed | No | |
| message | No | |
| toVersion | No | |
| advisories | No | |
| fromVersion | No | |
| packageName | No | |
| tokenMetrics | No | |
| advisoryCount | No | |
| breakingCount | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations already declare read-only/idempotent/non-destructive behavior, the description adds materially useful context: it is a metered lookup, misses are never billed, every API key carries one-off trial credit, and compact mode affects context usage. This goes beyond the annotations without contradicting them.
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 carry the core behavior, billing/response-format context, and alternative tool guidance without waste. The most important purpose is front-loaded, 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?
The tool is moderately complex, but the description covers the essential invocation context: registry coverage, exact-version comparison, evidence output, billing semantics, response format options, and the main sibling distinction. With a full output schema and comprehensive input schema, no critical guidance appears 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 input schema already documents every parameter with examples, enums, defaults, and constraints, so the description only needs limited parameter guidance. It adds meaningful value by explaining that responseFormat='compact' provides tokenizer-measured context savings and that 'full' is backward-compatible.
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?
The description names a specific verb, resource, and scope: compare two exact published npm or PyPI versions and return publisher-declared registry metadata changes. It also distinguishes itself from the sibling tool factreason_api_breaking_changes by clarifying that the sibling is for third-party HTTP APIs.
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?
It provides explicit when-to-use and when-not-to-use guidance: use for package metadata, use factreason_api_breaking_changes for third-party HTTP APIs, and consult changelogs for behavioral changes. It also states the responseFormat switching context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a persistent specification watch for one service; a Bearer API key is required and each key may hold up to 50 watches. Without webhookUrl, read future events from the polling endpoint; with a public HTTP(S) URL, FactReason sends signed POST callbacks after later spec changes. Duplicate or unsafe webhook registrations are rejected. This does not ingest a specification immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| webhookUrl | No | Optional public HTTP(S) URL for signed change callbacks; omit to poll | |
| serviceName | Yes | Service name to watch, e.g. "Stripe" or "SendGrid" |
| Name | Required | Description |
|---|---|---|
| error | No | |
| watch | No | |
| success | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond annotations, including authentication requirements ('Bearer API key is required'), rate limits ('each key may hold up to 50 watches'), callback signing behavior, and failure conditions ('Duplicate or unsafe webhook registrations are rejected'). These details (auth needs, rate limits, behavioral side-effects) are exactly the value-added context the rubric calls out. No contradictions with the annotations—in fact, the idempotentHint aligns with the duplicate rejection language.
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?
Four dense, information-rich sentences deliver purpose, auth requirements, limits, operational modes, error behavior, and an important exclusion (no immediate ingestion). Zero filler or redundancy—every clause earns its place. The structure frontloads the core action and layers details logically.
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?
Given the tool's moderate complexity (stateful watch creation with two operational modes) and the presence of a rich output schema that covers return values, the description covers the critical ground: auth, limits, mode selection, validation rejections, and non-ingestion behavior. Slightly more could be said about lifecycle management (e.g., how to identify or remove watches), but this is quite complete for a creation endpoint.
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?
With 100% schema coverage, the baseline is 3. The description enriches the webhookUrl parameter by clarifying the behavioral implications of omitting it (polling) versus providing it (signed POST callbacks), and it adds the watch-limit context tied to the serviceName scope. While the schema already documents format and examples, the description clarifies the semantic implications of each parameter choice, adding value above 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?
The description clearly states the tool's purpose with a specific verb+resource: 'Create a persistent specification watch for one service.' The scoping to 'one service' adds precision, but it does not explicitly differentiate from siblings like factreason_api_breaking_changes or factreason_deprecation_scan, which an ideal description might (e.g., noting this is for future changes vs. current analysis). Clear but lacking explicit sibling differentiation.
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 description provides excellent context on how to use the tool—explaining the polling mode versus webhook callback mode ('Without webhookUrl... with a public HTTP(S) URL...') and the key/limit constraints. It even includes a 'when-not' with 'This does not ingest a specification immediately.' However, it never names alternative tools or says 'use tool X for Y,' falling just short of the explicit alternatives required for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
Check claims against a fact-store: consistent, contradicts, or unverifiable — with a receipt.
Privacy-preserving synthetic health data generation. FHIR R4/R5 compliant.
Machine-readable entity discovery with provenance, trust and verified source evidence.
Add one secure layer between your agents and this server.
Most tools clearly target distinct tasks, and the descriptions cross-reference each other (e.g., package_upgrade_advisory vs api_breaking_changes, api_schema vs integration_brief). However, a few tools overlap in conceptual space—especially factreason_api_schema, factreason_auth_playbook, and factreason_integration_brief—so an agent may need to read the descriptions carefully.
All names share the factreason_ prefix and snake_case, but the naming pattern is mixed: some are noun phrases (api_schema, auth_playbook, deprecation_scan) while others use imperative verbs (create_key, discover_api, subscribe_spec_changes). The names are readable and not chaotic, but they do not follow a single predictable convention.
Eleven tools is well within the appropriate range, and the count fits the broad API-intelligence scope. Each tool seems to earn its place by covering a distinct phase of researching, comparing, or subscribing to API and package metadata.
The set covers discovery, schemas, auth, breaking changes, deprecation, package upgrades, and component spec lookup, which is a reasonably deep surface. However, the subscription feature creates watches but provides no tool to list, cancel, or delete them, and there is no balance/key management tool beyond key creation and top-up links.
