Cited news briefs and observed-corpus context. Free public reads; archives $0.10 or seven for $0.50.
Mark all currently unread matches on one owned watch as read. Requires watches:write and an Idempotency-Key.
| Name | Required | Description | Default |
|---|---|---|---|
| watchId | Yes | ||
| idempotencyKey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states a real state change (unread → read), scopes it to currently unread matches, and discloses the permission requirement. This adds useful context beyond the annotations while remaining consistent with readOnlyHint=false, idempotentHint=true, and destructiveHint=false.
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 with no wasted words: the first names the action and scope, the second gives prerequisites. The wording is front-loaded and every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter state-changing tool with no output schema, the description covers the operation, scope, ownership constraint, permission, and idempotency requirement. It does not describe the response, but that is not necessary for correct invocation of this 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?
With 0% schema description coverage, the description compensates by tying watchId to 'one owned watch' and calling out the Idempotency-Key requirement. A minor gap is that it does not explain the purpose of the idempotency key, but the parameter name and idempotentHint make it recoverable.
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 object: 'Mark all currently unread matches on one owned watch as read.' This clearly distinguishes it from generic watch-management siblings like update_watch and list_watches by targeting unread-match acknowledgement on a single owned watch.
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 context is clear: use it to acknowledge unread matches for a specific watch, and the prerequisites are explicit ('Requires watches:write and an Idempotency-Key'). It does not name alternatives or when-not-to-use cases, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Founding Pro saved watch. Requires watches:write; repeat the same Idempotency-Key to safely replay the same request.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| name | Yes | ||
| active | No | ||
| category | No | Only return replacements in this category. | |
| threshold | No | ||
| eventClass | No | ||
| idempotencyKey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the authorization requirement 'watches:write' and explains idempotency behavior by instructing to repeat the same Idempotency-Key to safely replay a request. These details go beyond the annotations, which only flag idempotentHint=true and destructiveHint=false. There is no 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 primary purpose is front-loaded, and the idempotency instruction is concise and actionable. 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?
This is a create operation with seven parameters and no output schema, but the description omits the meaning of most parameters, the response format, and the distinction from sibling tools. The short description is not enough for an agent to invoke this tool correctly without additional inference.
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 only 14%, so the description must compensate for parameters like name, mode, active, category, threshold, and eventClass. It only discusses the idempotency key, leaving the other six parameters without meaningful description. This is a significant gap for a 7-parameter 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 clearly states the operation: 'Create a Founding Pro saved watch,' with a specific verb, resource, and plan qualifier. It is unambiguous about creating, not updating or listing, but it does not explicitly name sibling tools to differentiate from them, so it misses the top bar.
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: call it when you need to create a new saved watch. It also gives a permission prerequisite ('Requires watches:write') and an idempotency replay instruction, but it does not discuss when to use this tool versus alternatives or when not to use it, so it stops at implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use to rank cited events in the latest completed edition by probable, rare, or overweighted mode. Keep research priors separate from measured current-edition counts. Do not describe the result as a forecast or a probability that an event occurred.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| limit | No | ||
| category | No | Only return replacements in this category. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and idempotent annotations, the description discloses that the tool operates on the latest completed edition and uses measured current-edition counts rather than prior expectations. The explicit warning not to describe results as a forecast or probability adds important interpretive context for the agent.
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 core purpose is front-loaded in the first sentence, and the two subsequent sentences provide essential constraints and cautions. Every sentence adds value.
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 covers the key scope and behavioral constraints, and the schema documents parameters. However, since there is no output schema, the exact return format is not described beyond implying a ranked list. For a tool of this simplicity, this is a minor 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?
Schema description coverage is only 33%, but the description connects the required 'mode' parameter to the ranking behavior, giving it meaning beyond the bare enum. The 'limit' parameter is self-explanatory given schema bounds, and 'category' already has a schema description. The description partially compensates for the low coverage on the most important 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 explicitly states the action ('rank'), the target resource ('cited events in the latest completed edition'), and the operating modes ('probable, rare, or overweighted'). This clearly distinguishes the tool from siblings like read_latest_edition or score_headline, which serve different purposes.
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 opening 'Use to rank...' provides a clear when-to-use instruction. It does not explicitly name alternatives or exclusions, but the specific task and scope make it obvious when this tool is appropriate. The added caution about research priors versus measured counts also guides correct usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export an edition as source-grounded Markdown or CSV. Requires member authorization with exports:read and an active Founding Pro entitlement.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| format | No | ||
| category | No | Only return replacements in this category. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the authorization requirement ('exports:read') and the Founding Pro entitlement, plus the source-grounded nature of the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence states the core action and formats, then adds the key prerequisite. There is no filler or redundant repetition of the title.
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 definition is adequate for basic invocation: format and category are inferable from the enum and schema description, and date follows from the edition context. However, with no output schema and all parameters optional, it does not explain default behavior (e.g., what happens with no date) or the exact return form.
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 only 33%, so the description needed to clarify parameter meaning but only conveys format values ('Markdown or CSV'). The 'date' parameter has no semantic explanation, and 'category' is only documented in the schema, not the description.
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 ('Export an edition') with a clear resource and output formats ('source-grounded Markdown or CSV'). It also distinguishes itself from sibling read/list tools by requiring exports:read and an active Founding Pro entitlement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this tool when a serialized Markdown or CSV export is needed, rather than reading an edition in-app. However, the description does not explicitly name alternatives like read_edition_by_date or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use for a current news brief or catch-up job. Return a five-story cited brief diversified across category, event class, and publisher by default. Use chronological or all for stable cursor paging. A balanced resumeCursor continues as a complete chronological change stream, even when the client repeats mode=balanced. Follow unreadCursor before saving resumeCursor. Do not use as a general web search or for events Probable did not observe.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | balanced | |
| limit | No | ||
| since | No | ||
| topic | No | ||
| cursor | No | ||
| category | No | Only return replacements in this category. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond that: default diversification, the return of a cited five-story brief, stable cursor paging semantics, and the unusual property that a balanced cursor continues as a chronological change stream even when the client repeats mode=balanced. It also clarifies scope by excluding unobserved events, consistent with openWorldHint=false.
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 purpose and return behavior. Every sentence carries useful information, especially the cursor semantics that would otherwise be hard to infer. The main drawback is that terms like resumeCursor and unreadCursor are introduced without much definition, assuming some familiarity with the response shape.
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 tool with no required parameters and no output schema, the description covers the return shape, default diversity behavior, cursor paging, unread-before-resume ordering, and exclusions. It is fairly complete, but since there is no output schema, the description could more clearly explain the relationship between the response cursors and the role of the since/topic parameters.
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 only 17%, so the description must compensate. It adds meaningful semantics for mode by recommending chronological or all for stable cursor paging, and it explains cursor-related behavior through resumeCursor and unreadCursor. However, it does not explain since, topic, limit, or the default behavior of mode beyond what the enum values already show, leaving several parameters underspecified.
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: get a current news brief, returning a five-story cited brief diversified by default across category, event class, and publisher. It also distinguishes itself from general web search and from events the system did not observe, which separates it from sibling tools like discover_events or edition readers.
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 explicitly says to use for a current news brief or catch-up job and warns not to use it as a general web search or for unobserved events. It also gives concrete paging guidance, such as using chronological or all for stable cursor paging and following unreadCursor before saving resumeCursor. It does not name specific sibling alternatives, but the when/when-not guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when a user supplies a headline or a source URL already observed by Probable and wants same-class context. Optional referenceContext adds explicit country, magnitude, industry or aviation scope for primary-source population references; missingFields and conflicts explain withheld matches. Unknown URLs are not fetched and instead request a headline. Do not use this to verify occurrence, compare unrelated event classes, or forecast.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive behavior; the description adds meaningful runtime behavior: unknown URLs are not fetched, and missingFields/conflicts explain withheld matches. This is useful context beyond the schema or annotations, though the exact response shape is still only partially described.
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 the primary usage front-loaded and the exclusions/edge cases in the final two sentences. No filler or repetition of schema constraints.
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 output schema, the description covers the key input scenarios, the referenceContext semantics, and the unknown-URL fallback. It leaves the exact notion of 'same-class context' somewhat implicit, but an agent has enough 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 fully describes constraints for headline, url, and referenceContext. The description goes further by explaining what referenceContext does (adds country, magnitude, industry, or aviation scope for primary-source population references) and telegraphs the role of missingFields/conflicts in interpreting results.
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 ('put ... in context') and resource (a headline or source URL already observed by Probable), and distinguishes itself by explicitly saying not to verify occurrence, compare unrelated event classes, or forecast. This clearly separates get_context from siblings like score_headline or discover_events.
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 states the triggering condition ('use when a user supplies a headline or source URL ... wants same-class context') and gives explicit negative guidance (do not use to verify occurrence, compare unrelated event classes, or forecast). It also specifies the unknown-URL fallback behavior, so an agent knows when to request a headline instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return Free and Founding Pro terms and available Stripe-hosted checkout URLs. Calling this tool does not open checkout or claim payment success.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a key behavioral guarantee beyond the annotations: 'Calling this tool does not open checkout or claim payment success.' This is valuable because Stripe URLs can easily be mistaken for triggering payment. Combined with readOnlyHint/idempotentHint, the agent understands the operation is side-effect-free.
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 deliver the core purpose, the exact data returned, and the critical behavioral caveat. No filler or redundant content; the most decision-relevant fact 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 tool, the description covers what is returned and the important non-effect. It does not explain the format of checkout URLs or whether terms are ever unavailable, but for this simple getter that is not a blocking 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 tool has zero parameters, and the schema is completely minimal. Baseline for zero params is 4; there is nothing more the description needs to clarify about parameters, and it does not attempt to invent any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and a clear resource (membership terms, including Free and Founding Pro, plus Stripe checkout URLs). It is sufficiently precise that an agent can distinguish it from the sibling tools, which concer watches, editions, and events rather than membership.
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?
No explicit when-to-use or alternative-routing guidance is provided. The context of the sibling tools makes the intent fairly clear, and the tool's name plus description imply it is the go-to for membership terms, but the description does not state exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the versioned category and event-class catalog used by score_headline. The editorial index is a legacy comparison weight, not an empirical probability.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those annotations: the catalog is versioned, and the 'probable' index is a legacy comparison weight rather than an empirical probability. This materially prevents misuse without contradicting 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?
Two sentences with no wasted words. The core return object is front-loaded in the first sentence, and the disambiguating caveat about the editorial index is placed second. 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 read-only, zero-parameter, low-complexity tool, the description is complete: it says what is returned, how to interpret the potentially misleading 'probable' label, and how the result relates to score_headline. No output schema exists, but the simplicity of the tool makes this sufficient.
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 an empty input schema, so parameter semantics are fully covered by the schema. Per the baseline for zero-parameter tools, a score of 4 applies; the description's substantive content is about return semantics, not parameters.
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 ('Return') and a specific resource ('versioned category and event-class catalog'), and explicitly ties it to score_headline. It also clarifies that the 'probable' in the title is not an empirical probability, removing a likely misinterpretation.
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 by identifying the catalog as the one used by score_headline, which tells an agent when this tool is relevant. It also warns against treating the editorial index as a probability. It does not explicitly name alternative tools or say when not to use it, but the sibling context makes the boundary reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every stored edition with public metadata, free/paid status, exact prices, and the URLs that can unlock paid content.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about the returned fields, including exact prices and URLs for unlocking paid content. However, it does not disclose response shape, pagination, ordering, or whether every edition is returned in one call.
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 a single, front-loaded sentence that states the action and the key output fields with no filler. Every clause adds information relevant to invoking the tool correctly.
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 list tool, the description is largely complete: it names the resource and the returned data categories. It lacks explicit output formatting or pagination details, and there is no output schema to compensate, which keeps it from a 5.
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 schema description coverage is 100%, so there are no parameter semantics to explain. The baseline for no-parameter tools is 4, and the description does not mislead or add unnecessary parameter-related noise.
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: 'List every stored edition' and enumerates the included fields (public metadata, free/paid status, prices, unlock URLs). It is clear that this is an enumeration tool rather than a single-edition reader, though it does not explicitly name sibling alternatives. The title's 'Probable editions' phrase is slightly ambiguous and is not mirrored in the description.
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?
No guidance is provided about when to use this tool versus siblings such as read_latest_edition, read_edition_by_date, or export_edition. The description implies a listing use case but gives no exclusions, prerequisites, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the member's saved monitors and recent matches. Requires member authorization with watches:read and an active Founding Pro entitlement.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond annotations by specifying the authorization requirement (watches:read) and the active Founding Pro entitlement prerequisite, which are not present in 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 wasted words. It front-loads the core action and object, then adds the essential access prerequisite. Every sentence contributes actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool, the description fully covers what is listed, who it belongs to, and the auth/entitlement conditions required. With no output schema present, the description still communicates the return scope—'saved monitors and recent matches'—which is sufficient for an agent to understand the tool's purpose and invocation constraints.
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 100% schema description coverage, so there is no parameter documentation burden on the description. The description's mention of 'the member' aligns with the implicit authorization context rather than any parameter, which is appropriate 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 clearly states a specific verb and resource: 'List the member's saved monitors and recent matches.' It distinguishes itself from sibling tools like create_watch and update_watch by framing this as a read-only listing operation. The title reinforces the object being listed, Founding Pro saved watches.
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 clear context for when the tool is appropriate: it lists the member's saved monitors and recent matches, and it explicitly calls out the required authorization scope and entitlement. It does not explicitly name alternatives or exclusions, but the read-versus-write contrast with siblings is clear enough for an agent to select this tool for listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a stored edition inside the seven-day public window. Older editions return an access boundary and links; this tool never bypasses membership or payment.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | America/Los_Angeles edition date in YYYY-MM-DD format. | |
| category | No | Only return replacements in this category. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond that: older editions return an access boundary and links, and crucially, the tool 'never bypasses membership or payment' — a significant guarantee for an agent deciding whether to use it in a membership-gated 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?
Two tight sentences with the core operation front-loaded and constraints efficiently placed. Every clause earns its place; there is no filler or redundant restatement of the tool name.
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 read tool with no output schema, the description covers the critical edge case (older editions) and the security boundary. It doesn't describe the shape of a successful response, but the simplicity of the operation and the strong annotations make this a minor gap rather than a serious omission.
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 date format and category enum are already fully documented in the schema. The description adds no additional parameter-level meaning, warranting the baseline score 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 uses a specific verb ('Read') and resource ('stored edition'), and immediately scopes it to the seven-day public window. This clearly differentiates it from siblings like read_latest_edition (latest vs. by-date) and export_edition (read vs. export) without needing to open schemas.
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 seven-day public window sets a clear temporal boundary for when this tool is appropriate, and the note about older editions returning an access boundary implies its limits. However, it does not explicitly state when to prefer this over read_latest_edition or export_edition, leaving some usage routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the latest source-grounded Probable edition. Every replacement is a different event observed in the same scan and category with a higher editorial comparison index; that index is not a measured occurrence rate.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Only return replacements in this category. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, and non-destructive nature, so the description adds value by clarifying that replacements are distinct events with a higher editorial comparison index and that this index is not a measured occurrence rate. This prevents a common misinterpretation of the output semantics.
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 and front-loads the main purpose before the caveat. It is reasonably concise, though the second sentence is dense with domain-specific jargon like 'editorial comparison index' that could be simplified without losing meaning.
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 read-only tool with one optional parameter and no output schema, the description provides enough to invoke it correctly and interpret results sensibly. It does not explicitly describe the return format, but the title and first sentence convey that an edition is being read, and the caveat covers the non-obvious semantics of replacements.
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 only parameter, category, is already fully described with an enum and a clear filter explanation. The description adds context about what a 'replacement' means, which indirectly helps interpret the filtered results, but it does not substantially enhance parameter-level understanding 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 a specific action ('Read') and resource ('the latest source-grounded Probable edition'), so the core purpose is unambiguous. The word 'latest' implies differentiation from read_edition_by_date, but no sibling is named explicitly, 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?
The phrase 'latest' implies the tool is appropriate when the most recent edition is needed, but there is no explicit guidance about when to prefer this over read_edition_by_date, list_editions, or export_edition. Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Classify one supplied headline and inspect coverage recurrence. Optional referenceContext adds explicit country, magnitude, industry or aviation scope. When sufficiently scoped, occurrenceReference separately supplies primary-source counts, exposure or published population rates with units and source periods. Missing fields, conflicts and hypothetical/disputed/historical wording are disclosed; news mentions never update source rates. Do not verify a headline, compare incompatible units, predict an outcome, or score a URL.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| referenceContext | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states that missing fields, conflicts, and hypothetical/disputed/historical wording are disclosed, and that 'news mentions never update source rates' — a key state-behavior guarantee. This goes well beyond the readOnly/idempotent annotations and tells the agent what side effects (or lack thereof) to expect.
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?
Five tight sentences are front-loaded with purpose, then scope, behavior, and prohibitions. Nothing is redundant with the title or schema, and every clause adds decision-relevant detail.
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 covers inputs, scoping, output hints (occurrenceReference with counts/rates/units), and edge-case handling, which is substantial for a tool with no output schema. The only minor gap is that 'occurrenceReference' is mentioned without explicitly labeling it as part of the response, which could momentarily confuse an agent.
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 zero schema description coverage, the description compensates by explaining that title is the headline and referenceContext adds explicit country, magnitude, industry, or aviation scope. It doesn't spell out the enum codes or numeric limits, but it gives the semantic purpose of each parameter rather than just echoing 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 opening sentence names a specific operation ('Classify one supplied headline and inspect coverage recurrence') on a specific resource, and the title anchors it to Probable's observed base rates. This clearly separates it from the sibling watch/edition/event tools, none of which perform headline scoring.
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 sets clear scope: one supplied headline, optional referenceContext for scope, and explicit prohibitions ('Do not verify a headline, compare incompatible units, predict an outcome, or score a URL'). It does not name alternative tools, but given the sibling set this is not necessary; the when-not guidance is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on one owned Founding Pro watch. Requires watches:write and an Idempotency-Key.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| name | No | ||
| active | No | ||
| watchId | Yes | ||
| category | No | ||
| threshold | No | ||
| eventClass | No | ||
| idempotencyKey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by disclosing the required OAuth scope (watches:write) and the mandatory Idempotency-Key, which are concrete operational constraints not inferable from the annotations alone. Since readOnlyHint and destructiveHint already cover the operation's safety profile, the additional auth and idempotency requirements earn credit here.
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 short sentences, front-loads the core purpose, and adds only the essential prerequisites. There is no fluff or redundant restating of the tool name.
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 an update tool with 8 parameters, no parameter descriptions, and no output schema, this description is too sparse. It omits crucial behavioral context such as whether omitted optional fields are unchanged, whether the update is partial or full, and what the response contains after the update succeeds.
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 0%, yet the description adds no meaning about any of the 8 parameters. It says 'Update fields' but does not explain which fields are updatable, how partial updates behave, or what values like mode, threshold, or category mean beyond their raw schema constraints.
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 ('Update') and a specific resource ('one owned Founding Pro watch'), which clearly indicates this modifies an existing watch rather than creating or listing one. It is clear enough, but it does not explicitly name or contrast sibling tools such as create_watch or acknowledge_watch to further differentiate.
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 phrase 'one owned Founding Pro watch' implies the tool should be used when modifying an existing watch you own, and the requirement for watches:write provides a prerequisite. However, it does not explicitly state when to prefer this over create_watch or acknowledge_watch, nor does it describe exclusions or scenarios where an alternative would be more appropriate.
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.
get_context1 field changedInput schema / anyOfPrevious value: -[
- {
- "properties": {
- "headline": {
- "maxLength": 500,
- "minLength": 8,
- "type": "string"
- }
- },
- "required": [
- "headline"
- ],
- "type": "object"
- },
- {
- "properties": {
- "url": {
- "format": "uri",
- "maxLength": 2048,
- "type": "string"
- }
- },
- "required": [
- "url"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "properties": {
+ "headline": {
+ "maxLength": 500,
+ "minLength": 8,
+ "type": "string"
+ },
+ "referenceContext": {
+ "additionalProperties": false,
+ "properties": {
+ "aviationScope": {
+ "const": "us_scheduled_part121",
+ "type": "string"
+ },
+ "countryCode": {
+ "pattern": "^[A-Z]{3}$",
+ "type": "string"
+ },
+ "industry": {
+ "enum": [
+ "51",
+ "00",
+ "31-33",
+ "44-45"
+ ],
+ "type": "string"
+ },
+ "magnitude": {
+ "maximum": 10,
+ "minimum": 0,
+ "type": "number"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "required": [
+ "headline"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "referenceContext": {
+ "additionalProperties": false,
+ "properties": {
+ "aviationScope": {
+ "const": "us_scheduled_part121",
+ "type": "string"
+ },
+ "countryCode": {
+ "pattern": "^[A-Z]{3}$",
+ "type": "string"
+ },
+ "industry": {
+ "enum": [
+ "51",
+ "00",
+ "31-33",
+ "44-45"
+ ],
+ "type": "string"
+ },
+ "magnitude": {
+ "maximum": 10,
+ "minimum": 0,
+ "type": "number"
+ }
+ },
+ "type": "object"
+ },
+ "url": {
+ "format": "uri",
+ "maxLength": 2048,
+ "type": "string"
+ }
+ },
+ "required": [
+ "url"
+ ],
+ "type": "object"
+ }
+]score_headline1 field changedInput schema / properties / referenceContextAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "aviationScope": {
+ "const": "us_scheduled_part121",
+ "type": "string"
+ },
+ "countryCode": {
+ "pattern": "^[A-Z]{3}$",
+ "type": "string"
+ },
+ "industry": {
+ "enum": [
+ "51",
+ "00",
+ "31-33",
+ "44-45"
+ ],
+ "type": "string"
+ },
+ "magnitude": {
+ "maximum": 10,
+ "minimum": 0,
+ "type": "number"
+ }
+ },
+ "type": "object"
+}acknowledge_watchcreate_watchdiscover_eventsexport_editionget_briefget_contextget_membershiplist_classeslist_editionslist_watchesread_edition_by_dateread_latest_editionscore_headlineupdate_watchClaiming 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!
Compact, citation-verifiable public web context for AI agents, paid per use with x402.
Evidence-first news archive: briefs, breaking news, search, Palestine claims, conflict monitor.
Neutral, bias-scored news for AI agents: compare left/right media-bias framing, fact-check receipts.
Free cross-lingual news briefings for AI agents across 89 languages. Read-only, hosted.
Add one secure layer between your agents and this server.
The watch and edition tools are clearly distinct, but get_context and score_headline overlap heavily—both accept a headline, share the referenceContext parameter, and disclose withheld/conflicting info—and get_brief vs read_latest_edition both serve 'what's the latest news' requests. The verbose 'do not use for' guardrails in the descriptions help, but they also signal that the boundaries are not naturally obvious.
All names follow snake_case verb_noun, with predictable patterns: list_* for collections, create/update/acknowledge for watch mutations, read_* for editions. Minor inconsistency exists between get_brief and read_latest_edition (both fetch news content) and between get_membership and list_watches (both return list-like info), but the overall scheme is readable and consistent.
14 tools sits within the typical well-scoped band, and each tool appears to serve a real product feature. The surface is slightly broad for a 'news' server, spanning saved-watch management, edition reading/export, headline analysis, and membership/checkout, which makes it heavier than a focused news reader.
Edition access (list/read/export) and the analysis workflow (score/context/discover) are well covered, but the watch lifecycle has no delete_watch, leaving agents unable to remove saved watches—a real dead end. There is also no story-level read or search tool, though the descriptions explicitly scope that out.
