Set up and run Cromanion, the autonomous conversion agent, on a website you manage for someone.
Define a conversion to count. This is not one more setting: it is the numerator of every impact figure your human will read, so a goal that fires on every pageview makes the agent look brilliant and tells them nothing. Idempotent — the same matcher twice creates one goal. Needs the goals permission.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Matcher: css_click, form_submit, page_view, mailto, tel, outbound, scroll_depth, dwell, custom_event. | |
| label | No | What your human will call it. Defaults to something readable. | |
| value | No | What the matcher matches — a selector, a path, a percentage, seconds. | |
| dollarValue | No | Optional worth of one conversion, for revenue figures. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include idempotentHint=true, and the description adds the useful domain meaning that the same matcher twice creates only one goal. It also discloses a prerequisite (goals permission) and conceptual side effect on impact figures, going beyond the boolean 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 dense sentences, each earning its place: clear definition, caveat about impact, and operational facts (idempotence and permission). The most important purpose is front-loaded.
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 four-parameter, write-side tool with no output schema, the description supplies selection context, a misuse warning, idempotence semantics, and the required permission. Combined with a fully described schema, an agent has what it needs to decide to call it and invoke 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 description coverage is 100%, so the structured field descriptions fully document type, label, value, and dollarValue. The description adds no parameter-specific syntax or format details, leaving the schema to carry the parameter 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?
States a specific action ('Define a conversion to count') on a distinct resource, giving the tool's role as the numerator of impact figures. The title and first sentence align, so there is no ambiguity, though it does not explicitly differentiate itself from sibling 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?
Gives clear context on when to use it: whenever one needs to define a conversion that will drive impact reporting, and it warns against overly broad goals such as firing on every pageview. It does not name an alternative tool or explicitly state when not to use it, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim another host for this site so its traffic counts, or give one up with remove: true. A DIFFERENT registrable domain must be proven on its own — publish this claim's challenge there too, then call again. Subdomains need no call at all: a claimed domain already covers them. Needs the site-config permission.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | A public hostname, e.g. shop.example.com. | |
| remove | No | Give the host up instead. Needs no proof — it only narrows what we listen to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses the proof challenge requirement, registrable-domain vs subdomain coverage, the narrowing effect of `remove: true`, and the site-config permission. These behaviors are material to invocation and are not otherwise visible in annotations or schema.
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?
Every sentence carries distinct high-value information: main action, remove behavior, proof condition, subdomain exception, and permission. It is front-loaded with the core action and avoids 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?
For a two-parameter tool with annotations already covering read-only/destructive/idempotent traits and no output schema, the description supplies everything needed to invoke it correctly: what to pass, when to skip it, permission requirements, and follow-up action for challenge publication.
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 the baseline is 3, but the description adds real meaning: `domain` is nuanced by registrable/subdomain differences, and `remove: true` is clarified as giving up a host with no proof and only narrowing what is listened to. This exceeds baseline without needing to restate schema 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 states a specific action: claim a host for the site so its traffic counts, or release one with `remove: true`. This clearly differentiates it from sibling tools like set_brand or verify_claim by focusing on host ownership/coverage, and the opening sentence 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?
It gives explicit when-to-use conditions: claim a new host, remove one, or do nothing for subdomains because a claimed domain already covers them. It also tells the agent when extra proof is needed (different registrable domain) and when it is not (`remove: true`), plus the required permission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-read the site, and name the pages that matter most so they are read first. You know this site's structure better than its owner does — seeding it is the cheapest real improvement to what the agent understands. Rate-limited: one crawl per 30 minutes. Needs the site-config permission.
| Name | Required | Description | Default |
|---|---|---|---|
| priorityUrls | No | Up to 10 paths or URLs to read first, e.g. ["/pricing", "/checkout"]. Anything unusable is handed back rather than dropped. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds useful behavioral context: the rate limit (one crawl per 30 minutes) and the permission requirement (site-config permission). It also discloses that unusable priority URLs are 'handed back rather than dropped,' which is a meaningful behavioral trait not inferable from annotations. No contradiction 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?
The description is short and front-loaded with the core behavioral intent. The second and third sentences add context (rate limit, permission) but the 'cheapest real improvement' phrasing is somewhat fuzzy and could be replaced with a more concrete statement. Overall, it earns its length but has mild rhetorical padding.
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 tool with a complete input schema and meaningful annotations, the description covers the important extras: rate limiting, permission requirements, and error behavior for unusable URLs. It does not explain return values or output format, but there is no output schema and the tool's purpose is a background crawl-like operation, so the absence is acceptable. The description is enough for an agent to decide when and how to invoke it.
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 the baseline is 3. The description does add a bit of extra meaning by framing priorityUrls as 'paths or URLs to read first' and shows example values, but the schema already describes them fully. There is no additional detail about format, validation, or side effects beyond what the schema provides, so it stays at the baseline.
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 is evocative ('Re-read the site, and name the pages that matter most so they are read first') but it never states a direct verb+object like 'crawl the site and prioritize URLs' in plain operational terms. It communicates intent and strategy rather than a crisp tool function, and while it is distinct from siblings in spirit, the purpose is somewhat wrapped in metaphor about 'seeding' and 'cheapest real improvement.'
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 implies when to use it (to improve the agent's understanding of the site by seeding important pages) and mentions the rate limit and permission requirement, but it does not explicitly contrast with siblings or say when not to use it. A clear alternative list is absent; the 'site-config permission' is a useful prerequisite, but guidance is still mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rule on one thing from cromanion_pending: pass its kind and id back unchanged with a decision. approve / reject for everything; pause additionally for a playbook rule. Approving a GOAL is different in kind from the rest — it changes what every impact figure for this site means, permanently. You cannot edit rule text here, only rule on it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The item's id, exactly as cromanion_pending returned it. Ids are not shared across kinds. | |
| kind | Yes | Which queue the item came from. Copy it back from cromanion_pending unchanged. | |
| decision | Yes | A status and nothing else — there is no way to edit an item's text here. `pause` applies only to a playbook_rule. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a meaningful behavioral warning beyond the annotations: approving a GOAL permanently changes what impact figures mean for the site. It also reinforces that this endpoint only records a decision, not text edits. The annotations already cover read-only/destructive hints, so the extra goal-specific warning is valuable context.
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 dense and front-loaded, with the core instruction in the first sentence. Every subsequent sentence earns its place: decision constraints, the significant GOAL caveat, and the no-edit limitation. It is concise without being under-specified.
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 three-required-parameter decision tool with full enum documentation and helpful annotations, this description is complete. It covers where inputs come from, how to pass them back, which decisions are allowed, the important GOAL special case, and what cannot be done. No output schema is necessary for an acknowledgment-style 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?
Schema description coverage is 100%, and the description largely restates what the schema already says, such as copying kind/id unchanged and pause applying only to playbook_rule. It adds no significant new per-parameter meaning, so the 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?
The description states a specific action ('Rule on one thing') and a specific resource ('from cromanion_pending'), then enumerates the possible decisions. It also distinguishes the tool from editing tools by saying 'You cannot edit rule text here, only rule on it.' This makes the tool's purpose unmistakable.
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 clearly tells the agent to take one item from cromanion_pending and pass its kind and id back unchanged. It also gives decision-specific guidance: approve/reject for everything, pause only for a playbook_rule. However, it does not explicitly name alternative sibling tools or provide a when-not-to-use list beyond the no-editing constraint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List what your human has allowed this agent to do, and what they have not. Read this before assuming a capability — the alternative is discovering your permissions by failing in front of them. You cannot change these yourself; only your human can, in their console.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond its readOnlyHint annotation, the description adds that the agent cannot change permissions itself and that only the human can do so in their console. It also discloses that the tool reports both allowed and disallowed actions, giving a full picture of its behavior.
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, each earning its place: the first defines what the tool returns, and the second gives essential usage guidance. The most important information is front-loaded.
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-only introspection tool, the description is complete: it states what the output will tell the agent, when to use it, and what the agent cannot do with it. No output schema is needed because the return content is described clearly.
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 has zero parameters, so there is no parameter semantic burden for the description to carry. The baseline of 4 applies because nothing is missing and no ambiguous parameter exists.
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 states a specific verb and resource: it lists the agent's permitted and forbidden capabilities. It clearly distinguishes this tool from the action-oriented sibling tools by positioning it as a permissions introspection tool.
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 explicitly instructs the agent to read this before assuming any capability, and warns that the alternative is failing in front of the human. This gives a clear, actionable when-to-use rule, even if it does not name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the agent has actually changed: visitors who saw it versus the 10% held back as a control. Read liftStatus before reporting anything — learn means nothing has been shown yet and insufficient means the arms are too small to tell signal from noise. Neither is 'no lift'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds critical behavioral context: the comparison uses a 10% holdout, and both `learn` and `insufficient` statuses must not be interpreted as 'no lift'. This prevents a common misinterpretation and is exactly the kind of non-obvious behavior an agent needs to know.
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 tightly written sentences: first the core definition, then the required action, then the interpretive warning. Front-loaded and free of filler; 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?
For a zero-parameter read tool with no output schema, the description supplies the essential interpretation context: control-group comparison, status semantics, and the 'not no-lift' trap. An agent has enough information to call and interpret this tool correctly without additional documentation.
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 has zero parameters and the schema coverage is 100%, so the schema already documents everything. The description adds no parameter-level detail, but none is needed; this is the appropriate baseline for a parameterless tool.
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 defines the resource precisely: 'what the agent has actually changed: visitors who saw it versus the 10% held back as a control.' It clearly conveys that this is a measurement tool, not a mutation tool. However, it lacks an explicit verb like 'read' or 'get' for the tool action and does not name sibling alternatives, so it stops short of full 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?
It gives clear usage context: read `liftStatus` before reporting anything, and understand the meaning of `learn` and `insufficient` before drawing conclusions. This is actionable guidance, though it does not explicitly mention when not to use the tool or point to alternatives among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set where captured leads are delivered: an https webhook, a connected HubSpot portal, or off. Note before you use it: this is the one change that leaves no other trace — forms keep working and visitors keep being thanked while the addresses go somewhere new — so every change emails your human and appears on their notifications screen. Needs the integrations permission.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Where leads go: `webhook` posts them to your `target` URL, `hubspot` to the connected portal, `off` stops delivery while forms keep working. | |
| target | No | The https webhook URL. Not needed for hubspot or off. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations, explaining that this change leaves no other visible trace while forms keep working, and that every change emails the human user and appears on their notifications screen. This is critical behavioral context for a destructive, side-effect-heavy operation and is not available from the annotations or schema.
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 front-loaded with the core purpose in the first sentence and then devotes the second to important warnings. The second sentence is somewhat long but every clause adds necessary context about side effects and permissions, so it remains efficient.
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 two-parameter configuration tool with full schema coverage and no output schema, the description covers purpose, options, permission requirements, and silent side effects. Nothing essential for an agent to understand the impact of invoking this tool 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 description coverage is 100%, so the schema already fully documents the kind enum and target parameter. The description adds no further parameter-specific meaning beyond what the schema provides, so the baseline score of 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?
The description states a specific action and resource: "Set where captured leads are delivered" and enumerates the three concrete destinations (webhook, HubSpot, off). This clearly distinguishes it from sibling set_* tools, which target different resources like brand, mode, or voice.
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 implies its use case by naming the exact settings it controls and the available destination options. It also provides a prerequisite ("Needs the integrations permission"), which is useful usage guidance. It does not explicitly name alternative tools or exclusion conditions, but none of the siblings cover lead destinations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start signing your human up for Cromanion (the autonomous conversion agent) on a site you manage. Creates NOTHING yet — no account, no key, no charge: it returns a challenge you must publish on the site to prove you control it, plus the secret you will authenticate with afterwards. Store the secret; it is shown once. Refuses if the address already has an account, because controlling a site does not prove controlling a mailbox.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | Optional: what you call yourself, for support and audit. | |
| Yes | Your human's email. It becomes the account's login. | ||
| siteUrl | Yes | The public URL of the site to optimize, e.g. https://example.com. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry readOnly=false, openWorld=false, idempotent=false, and destructive=false, so the description carries most behavioral disclosure. It reveals non-obvious side effects (creates nothing yet), one-time secret display, an ownership proof requirement, and a refusal condition with its rationale. This is substantial and specific.
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 dense, purposeful sentences; the core action is front-loaded and the critical caveats (returns challenge/secret, store secret, refuses duplicates) are packed efficiently. No filler 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?
With no output schema, it explains the two key return values (challenge and secret) and the required action (publish on the site). It could be slightly more complete by naming the next verification step or specifying how the challenge should be published, but the essential operational context is present.
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%: email and siteUrl are already described in the schema. The description adds no additional per-parameter semantics beyond what the schema provides, which makes the baseline 3 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?
The description is specific: 'Start signing your human up for Cromanion... on a site you manage' names the verb, resource, and scope. It clarifies what it does not do ('Creates NOTHING yet — no account, no key, no charge') and contrasts with the later verification step by returning a challenge/secret, so it is distinguishable from siblings like cromanion_verify_claim.
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 gives clear context: use it to begin signup for a site you manage, and it refuses when the address already has an account. It does not explicitly name alternative sibling tools or say 'use X instead', so it stops short of full when-to-use/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.
Everything on this site that is waiting for a decision: page rewrites the agent wants to make, rules it distilled from real sessions, conversions it spotted but has never counted, and pages your traffic found that the crawl missed. This is the client's actual job in the console, in one call. Rule on an item with cromanion_decide.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add value by enumerating the categories of pending items and implying that this call only surfaces them while decisions happen via cromanion_decide. However, it never explicitly states that the tool is read-only, nor does it describe the response format or any side effects, leaving a meaningful transparency gap.
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 compact and front-loaded: it states the core concept first, uses concrete examples to clarify scope, and ends with actionable routing to cromanion_decide. Every sentence adds value and there is no redundant 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?
For a zero-parameter tool, the description is largely sufficient: it explains what the result set contains and directs the agent to the right follow-up tool. It could be more complete by explicitly confirming that the call is observational and describing the return shape, especially since no annotations or output schema are available to fill that gap.
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 is empty, and schema description coverage is 100%, so there are no parameters for the description to explain. The description appropriately focuses on the meaning and contents of the result set rather than parameter details.
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 defines the tool as a consolidated view of everything waiting for a decision, including rewrites, distilled rules, uncounted conversions, and missed pages. It also differentiates it from cromanion_decide by directing rule-making to that sibling. However, it lacks an explicit action verb like 'list' or 'get,' so the retrieval behavior is implied rather than directly stated.
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 clear context: this is the client's main console job in one call, implying this is the review surface for pending work. It also explicitly routes decision-making to cromanion_decide, giving an actionable alternative. It does not spell out when not to use the tool, but for a zero-parameter listing tool that is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adjust the palette, fonts and button styling the agent paints its surfaces with. The crawl guesses these from a stylesheet; you probably know the real tokens. Cosmetic only — it changes how the agent looks, never what it may say. Needs the brand permission.
| Name | Required | Description | Default |
|---|---|---|---|
| colors | No | Hex per role, e.g. {"primary":"#1a1a2e"}. Roles come from cromanion_site_status. | |
| ctaFill | No | Primary button background, hex. | |
| ctaText | No | Primary button text colour, hex. | |
| bodyFont | No | CSS font-family stack for body text, e.g. "Inter, sans-serif". | |
| ctaRadius | No | Primary button corner radius, e.g. 8px. | |
| headingFont | No | CSS font-family stack for headings, e.g. "Inter, sans-serif". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the tool is cosmetic-only and does not affect what the agent may say, which is meaningful behavioral context. It also adds the required permission, which the annotations do not specify. No contradiction with the idempotent or destructive hints exists.
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 with no wasted words: the first states the action, the second explains why the user may need it, and the third defines scope and permission. Every sentence earns its place and the key purpose is front-loaded.
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 low-complexity cosmetic mutation with zero required parameters and rich per-parameter schema descriptions, the description covers purpose, usage rationale, permission, and behavioral boundaries. Nothing essential is missing for an agent to decide whether to invoke it.
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%, so the schema already documents all six parameters clearly. The description adds only a high-level grouping ('palette, fonts and button styling') and does not add meaning beyond what the schema provides, which fits the baseline of 3.
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: 'Adjust the palette, fonts and button styling'. It clearly distinguishes this tool from content-affecting or mode-setting siblings by emphasizing it changes how the agent looks, never what it may say.
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 useful context for when to call it: the crawl guesses brand tokens from a stylesheet, and the user probably knows the real ones. It also states the permission prerequisite ('Needs the brand permission'), though it does not explicitly list siblings to avoid using.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the share of visitors held back from the agent so its effect stays measurable (0.05–0.5). Changing it splits the measurement window: periods either side are compared separately and never pooled. Needs the measurement permission.
| Name | Required | Description | Default |
|---|---|---|---|
| share | Yes | Fraction held back, e.g. 0.1 for 10%. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses a non-obvious behavioral consequence: changing the holdout splits the measurement window and periods are compared separately and never pooled. It also states the permission requirement. This adds meaningful context beyond readOnlyHint and destructiveHint.
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 action and range, the behavioral consequence, and the permission requirement. It is front-loaded with the core action and free of 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?
For a single-parameter setter with no output schema, the description covers the action, the parameter range, the behavioral side effect, and the required permission. The annotations cover safety traits. Nothing essential is missing for an agent to invoke this 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 input schema already describes the share parameter with an example, so the baseline is 3. The description adds the explicit valid range (0.05–0.5) and clarifies that the share represents visitors held back, which adds semantic value 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 states a specific action ('Set the share of visitors held back'), the resource (agent holdout), and the intended purpose ('so its effect stays measurable'). It clearly distinguishes itself from sibling tools like cromanion_set_mode or cromanion_set_brand by naming the exact measurement concept being modified.
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 conveys clear context: it is for adjusting the holdout share, and it warns that changing it splits the measurement window and requires the measurement permission. It does not explicitly name alternatives or state when not to use it, but the purpose is specific enough that an agent can infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch the agent on. learn watches and shows visitors nothing; act lets it intervene in your human's name. customizeMode is a separate axis for rewriting their own page copy: off, shadow (propose only) or live. Needs the activation permission.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | `learn` watches and shows visitors nothing; `act` lets the agent intervene in your human's name. Omit to leave it as it is. | |
| customizeMode | No | Rewriting your human's own page copy, a separate axis from `mode`: `off`, `shadow` (propose only, nothing shown) or `live`. Omit to leave it as it is. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explaining what each mode actually does: `learn` watches without showing visitors anything, `act` intervenes in the user's name, `shadow` only proposes, and `live` applies rewrites. It also surfaces the permission requirement. This gives an agent a realistic picture of the tool's behavioral impact without contradicting the declared 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 carry all essential information: the core action, the meaning of each mode value, the separation of the two axes, and the permission prerequisite. There is no filler, and the most important framing is front-loaded.
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 simple two-parameter, fully enum-constrained tool, the description is largely complete: it explains both axes, the effect of each value, and the permission needed. It does not describe the return value or error behavior, but with no output schema and an idempotent state-setting operation, that is a minor gap rather than a blocking one.
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%, so the schema already documents both parameters and their enum values. The description paraphrases the same semantics and adds the useful framing that the two parameters are independent axes, but it does not add significant new parameter-level meaning 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 opens with a clear verb and resource ('Switch the agent on') and then immediately defines the two independent axes, `mode` and `customizeMode`. It distinguishes the tool's purpose from the broader set of config tools and clarifies that `customizeMode` is a separate axis rather than a subset of `mode`.
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 clear context for when to use the tool: when activating the agent, switching between learning and acting, or setting page-copy customization. It states the activation-permission prerequisite. It does not explicitly name sibling alternatives or state when not to use it, but for this simple state-setting tool the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write the facts the agent may state to visitors, and the things it must never say. Plain sentences, one idea per line; start a line with 'never' to forbid something. Anything you write that your human's own pages do not already state is attributed to THEM as the source — so write only what they have told you is true. Every rule is checked against your own text and the site's vocabulary, and anything ungrounded is silently dropped: read the returned lines to see what actually survived. Your human sees each line attributed to you. Needs the voice permission.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The whole guidance, replacing what is there. An empty string clears it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint and readOnlyHint annotations, the description reveals important behaviors: ungrounded lines are 'silently dropped' and the agent must read `lines` to see what survived; content is attributed to the human as source; the human sees each line; and the voice permission is required. These are material behaviors an agent cannot infer from the schema or 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 front-loaded with purpose, then moves through format, attribution, validation/drop behavior, visibility to the human, and permission. Every sentence earns its place; the length is justified by the amount of non-schema behavioral information an agent needs.
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 tool with no output schema, the description covers what to write, how to format it, the failure/drop mode, the required permission, and how to inspect the result via the returned `lines`. No critical gap remains for correct invocation.
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 full schema coverage the baseline is 3, but the description adds substantial meaning to the single `text` parameter: plain sentences, one idea per line, 'never' prefix for prohibitions, attribution semantics, and validation against the site's vocabulary. This goes well beyond the schema's generic 'replacing what is there.'
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 action and resource: 'Write the facts the agent may state to visitors, and the things it must never say.' This goes beyond the name to define what the voice tool controls, and its focus on agent-stated facts distinguishes it from brand, mode, and site 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?
The imperative 'Write the facts...' gives clear context for when to call the tool: whenever the agent's permitted or forbidden statements need to be set. It also discloses the prerequisite 'Needs the voice permission,' but it does not explicitly contrast with alternatives such as set_brand or set_mode, nor state exclusionary conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the site you provisioned: whether the tag is actually live (a beacon received from your own domain, not merely a snippet handed to you), how the crawl is going, and the plan. Poll this after installing the snippet. Requires the claim secret as a bearer token.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a read-only operation, and the description adds useful behavioral context: it checks for a real beacon from your own domain rather than a handed-off snippet, includes crawl progress and plan status, and requires a bearer-token secret. No contradiction 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 tight sentences, each earning its place: what is checked, when to poll, and what auth is required. Core purpose is front-loaded with no 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?
For a zero-parameter, read-only status tool with a clear auth requirement and polling trigger, the description covers everything needed to call it correctly. No output schema exists, but the description reasonably indicates what the status contains: tag liveness, crawl progress, and the plan.
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?
There are no parameters in the schema, so the baseline is 4. The description adds the only relevant input context (claim secret as bearer token), which is auth-related rather than a schema parameter.
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 clear verb and resource: check the provisioned site, including whether the tag is live, how the crawl is going, and the plan. The beacon-from-your-own-domain detail sharply distinguishes it from sibling tools like cromanion_crawl or cromanion_verify_claim.
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 gives explicit timing guidance ('Poll this after installing the snippet') and a prerequisite (the claim secret as a bearer token). It does not name alternatives or say when not to use it, so it stops short of full differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose where the agent may speak and what those places look like: which layout surfaces are enabled, whether the exit modal is allowed, custom CSS, and per-surface HTML. Markup and CSS are re-checked against an allowlist on every visitor — anything that could run, or fetch a remote resource, is silently removed, so compare what comes back with what you sent. Needs the surfaces permission.
| Name | Required | Description | Default |
|---|---|---|---|
| enabled | No | Surfaces the agent may use: inline_hint, card, sticky_bar, bottom_sheet, inline_block, cta_tooltip. | |
| customCss | No | CSS applied inside the intervention's shadow root. An empty string clears it. | |
| templates | No | Per-surface HTML, keyed by surface. Use {{message}}, {{cta_label}} and {{cta_url}} as placeholders. | |
| allowModal | No | Allow the page-blocking exit modal. Off by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses that markup/CSS is re-checked against an allowlist on every visitor, that executable or remote-fetching content is silently removed, and that the agent should compare the response against what was sent. It also notes the required permission. This goes well beyond the bare schema.
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 appropriately sized and front-loaded: it states the purpose first, then lists configuration areas, then gives the critical sanitization warning and permission requirement. Each sentence earns its place, though the opening metaphor is slightly indirect.
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 no annotations and no output schema, the description is reasonably complete for a configuration tool. It covers all four parameter areas, explains the permission requirement, and warns about response differences caused by sanitization. It does not specify the exact response shape, but the compare instruction partially compensates for the missing 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 description coverage is 100%, so the parameters are already well documented. The description adds relevant context about allowlist checking and sanitization for customCss and templates, but it does not significantly expand per-parameter meaning 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 identifies the tool's purpose: configuring where the agent may speak and what those surfaces look like. It enumerates the exact settings (enabled surfaces, exit modal, custom CSS, per-surface HTML), distinguishing it from sibling tools by domain even though it does not explicitly name a sibling alternative.
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 implies usage context—use this when choosing agent speaking surfaces—and provides a prerequisite ('Needs the surfaces permission'). However, it does not explicitly state when to use this tool over alternatives or when not to use it, leaving the decision partially to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Stripe Checkout link for a paid plan (pro or growth). Returns a URL and nothing else — YOU do not pay and cannot: give the link to your human, who enters their own card. The site works on the free plan meanwhile. Requires the claim secret as a bearer token.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes | Which paid plan the link should check out: pro or growth. The site keeps working on free until your human completes it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral details beyond the annotations: the response is only a URL, the agent cannot pay and must not attempt to, the human performs the checkout, and a claim secret bearer token is required. This fully discloses the important operational boundaries and auth requirement.
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?
Every sentence earns its place: it states the core function, the exact return value, the division of payment responsibility, the continued free-plan operation, and the auth requirement. The important behavioral constraints are front-loaded without 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?
For a single-parameter tool with no output schema, the description is complete: it specifies the input, the return value, the authentication requirement, and the expected interaction flow. No critical operational detail 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 schema already covers the single parameter completely with an enum and description. The description reiterates the plan options but adds little new semantic information beyond what the schema provides, so the baseline score of 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?
The description specifies a precise action — getting a Stripe Checkout link for a paid plan (pro or growth) — and clearly distinguishes this from sibling tools by stating it returns a URL and nothing else. The resource and scope are 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 clearly establishes the context: the AI agent should obtain the link and hand it to the human, who pays with their own card, while the free plan continues to work. It does not explicitly name alternatives or exclusions, but the use case is specific enough to guide tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Redeem a claim once you have published one of its three proofs (a /.well-known file, a tag, or a DNS TXT record). On success it creates the account and the site and returns the tracking snippet to install. Idempotent — safe to retry. Requires the claim secret as a bearer token.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining the success effect (creates account and site), the return value (tracking snippet), the idempotency guarantee, and the auth requirement (claim secret as bearer token). It aligns with the annotations, reinforcing idempotentHint=true and destructiveHint=false 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 focused sentences cover the precondition, the outcome, the return value, idempotency, and authentication. Every clause earns its place and the most important information is front-loaded.
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 tool with no input parameters and no output schema, the description is remarkably complete: it states what the agent must have done first, what will happen on success, what the response contains, and what credentials are needed. This is sufficient for correct invocation.
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 is empty and there are zero parameters, so the baseline is 4. The description still adds meaningful operational context by explaining that the claim secret is supplied as a bearer token rather than as a schema parameter.
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 ('Redeem') with a clear resource ('a claim') and states the outcome: creates the account and site and returns the tracking snippet. It also clarifies the conditions under which redemption is valid, distinguishing this from nearby claim-related sibling tools like 'claim_domain' or 'open_claim'.
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 context for when to call the tool: after publishing one of three listed proofs. It does not explicitly name alternatives or state when not to use it, but the prerequisite condition is clear enough to guide correct invocation.
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. Dates show when Glama detected each change.
cromanion_decide3 fields changedInput schema / properties / decision / descriptionAdded value: +"A status and nothing else — there is no way to edit an item's text here. `pause` applies only to a playbook_rule."Input schema / properties / id / descriptionAdded value: +"The item's id, exactly as cromanion_pending returned it. Ids are not shared across kinds."Input schema / properties / kind / descriptionAdded value: +"Which queue the item came from. Copy it back from cromanion_pending unchanged."cromanion_lead_destination1 field changedInput schema / properties / kind / descriptionAdded value: +"Where leads go: `webhook` posts them to your `target` URL, `hubspot` to the connected portal, `off` stops delivery while forms keep working."cromanion_set_brand2 fields changedInput schema / properties / bodyFont / descriptionAdded value: +"CSS font-family stack for body text, e.g. \"Inter, sans-serif\"."Input schema / properties / headingFont / descriptionAdded value: +"CSS font-family stack for headings, e.g. \"Inter, sans-serif\"."cromanion_set_mode2 fields changedInput schema / properties / customizeMode / descriptionAdded value: +"Rewriting your human's own page copy, a separate axis from `mode`: `off`, `shadow` (propose only, nothing shown) or `live`. Omit to leave it as it is."Input schema / properties / mode / descriptionAdded value: +"`learn` watches and shows visitors nothing; `act` lets the agent intervene in your human's name. Omit to leave it as it is."cromanion_upgrade_link1 field changedInput schema / properties / plan / descriptionAdded value: +"Which paid plan the link should check out: pro or growth. The site keeps working on free until your human completes it."cromanion_add_goalcromanion_claim_domaincromanion_crawlcromanion_decidecromanion_grantscromanion_impactcromanion_lead_destinationcromanion_open_claimcromanion_pendingcromanion_set_brandcromanion_set_holdoutcromanion_set_modecromanion_set_voicecromanion_site_statuscromanion_surfacescromanion_upgrade_linkcromanion_verify_claimClaiming 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, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
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!
Provision and manage a ClaraConverts AI conversion-agent widget: pricing, trials, account setup.
An AI agent that runs your online business: products, orders, customers, email, and sites.
Set up and manage conversion tracking by chatting with your AI assistant.
Agentic visitor analytics — five tools that hand the next CRO fix to your coding agent.
Add one secure layer between your agents and this server.
Most tools target a distinct resource or action: goals, domains, pending decisions, impact, permissions, and provisioning are clearly separated. A few visual/claim-related tools (set_brand vs surfaces; open_claim vs verify_claim vs claim_domain) could be confused, but their descriptions resolve the boundaries well.
The cromanion_ prefix and set_* configuration tools provide some consistency, but the set mixes verb_noun (add_goal, verify_claim), bare verbs (crawl, decide), and noun-only resources (grants, impact, pending, site_status). It remains readable, but the pattern is not uniform.
17 tools is on the heavy side for a single server, though each tool has a real job and the breadth reflects provisioning, configuration, measurement, and approvals. It is not bloated, but it is above the ideal 3-15 range.
Core workflows are covered: provisioning, claiming, configuring, reviewing pending items, measuring impact, and managing permissions. However, there is no general way to read current goal/config state or delete goals, and some lifecycle endpoints like account removal are absent, leaving notable but workable gaps.
