BetterPost
Server Details
Finds timely sources across news, social, and the web and writes posts worth publishing.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4/5 across 22 of 22 tools scored. Lowest: 2.9/5.
Each tool serves a clearly distinct function: source management, story import, project lifecycle, content generation/derivation, settings, and status checks. No two tools have ambiguous overlap, as even similar operations like add_source vs add_story are differentiated by source type.
All tools follow the consistent pattern `betterpost_<verb>_<noun>` in snake_case, making the set predictable and easy to navigate. The verbs are descriptive (add, create, delete, list, get, generate, etc.) and adhere to a uniform style.
With 22 tools, the surface is comprehensive for a content generation platform, covering all major operations without being overwhelming. The count is slightly above the typical 3–15 range but well-justified by the domain's complexity.
The tool surface covers the full lifecycle: project CRUD, source and story management, content generation and transformation, settings, usage tracking, and advanced operations like topic suggestion and coverage expansion. No obvious gaps exist for the intended use case.
Available Tools
22 toolsbetterpost_add_sourceAdd sourceAInspect
Adds a source to a project and fetches it immediately (bounded by a few seconds), returning storiesAdded so the next generate_content can use it; if it is still fetching it returns fetched:false with a note. Doubles as manual source import: paste any URL (RSS/Atom feed, article, or a page, profile, or post on a supported platform) and leave type as autodetect, or create a recurring keyword search by setting value to the search terms and type to a search kind (see type).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| type | No | Source kind (one of the enum values; defaults to 'autodetect'). 'autodetect' infers the kind from `value` (a URL): RSS/Atom feeds, web pages, news, Reddit subreddits, X and Bluesky posts/users, LinkedIn company pages, Instagram profiles, YouTube videos, and Hacker News items — leave it as 'autodetect' for any URL. For a recurring keyword search that re-runs over time, set `value` to the search terms and pick a search kind: 'web-search', 'reddit-search', 'youtube-search', 'x' (X/Twitter search), or 'bluesky' (Bluesky search). | autodetect |
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| value | Yes | ||
| projectId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| note | No | |
| source | Yes | |
| fetched | Yes | |
| storiesAdded | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide basic hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true), but the description adds valuable behavioral context: fetching is bounded by a few seconds, returns 'storiesAdded' or 'fetched:false' with a note, and supports open-world URL types. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly long but efficient, front-loading the core purpose and then adding necessary details. Each sentence adds value without redundancy. It could be split into two sentences for readability, but overall it's well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, output schema exists), the description covers key aspects: behavior, parameter usage, and return values. It explains the open-world nature and search creation. The output schema likely handles return value documentation, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (40%), but the description compensates by detailing the 'value' parameter (accepts any URL or search terms), the 'type' parameter (explains each enum option and autodetect behavior), and the 'token' parameter (usage context). It adds significant meaning beyond the schema's short descriptions.
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 action ('adds a source to a project') and the specific resource ('source'). It distinguishes itself from sibling tools like 'remove_source' and 'list_sources' by explaining the fetch-and-return behavior, making the 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?
The description explains when to use the tool (to add a source, import a URL, or create a recurring search) and gives examples of URL types and search kinds. While it doesn't explicitly state when not to use it, the context implies no strict exclusions. The guidance is clear but could be more explicit about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_add_storyAdd storyAInspect
Manually imports a story you read about from its URL (pinned relevance, flagged is_manual) so generation can draw on it.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| title | No | ||
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| summary | No | ||
| projectId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| storyId | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) with possible side effects (openWorldHint=true) and non-idempotent behavior. The description adds context about 'pinned relevance, flagged is_manual' but does not disclose duplicate handling, error behavior, or authentication requirements beyond what is in the schema. 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 a single, well-structured sentence of 32 words that immediately conveys the action and purpose. There is no redundant information, and every word contributes 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?
Given the tool has 5 parameters (2 required) and an output schema exists, the description is minimally adequate. However, it lacks details on prerequisites (e.g., valid token/project) and the import process, which would be helpful for a tool with medium complexity.
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 20% (only 'token' has a description). The tool's description does not explain parameters beyond the URL, missing context for 'title', 'summary', 'projectId', and 'token'. It fails to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'imports a story from its URL' and specifies the resource (story) and method (manual). It distinguishes itself from siblings like 'betterpost_add_source' by focusing on importing a specific story rather than adding a source.
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 when you have a specific story URL to manually add, but it does not provide explicit guidance on when not to use this tool or mention alternatives such as 'betterpost_add_source' or automatic import methods. The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_create_projectCreate projectAInspect
Create a content project. Slow, one-shot: infers config (criteria, industry, tone), discovers sources, and gathers/ranks an initial set of timely stories. Best called after the inferred audience, description, and tone have been confirmed with the user, since the config shapes everything downstream.
| Name | Required | Description | Default |
|---|---|---|---|
| tone | No | ||
| title | Yes | ||
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| audience | Yes | ||
| description | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| tone | Yes | |
| _note | No | One-time note — e.g. a freshly issued demo token to save to durable memory and reuse. |
| reason | No | |
| warming | Yes | |
| criteria | Yes | |
| industry | Yes | |
| projectId | Yes | |
| hasXSource | Yes | |
| storiesGot | Yes | |
| storiesGoal | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds behavioral context beyond annotations: 'Slow, one-shot' and describes multi-step inference and discovery. No contradiction with annotations (readOnlyHint=false, etc.).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first states action and key traits, second gives usage guidance, third adds behavioral context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (multi-step creation) and presence of output schema, description covers when to use, what it does, and key traits. Does not explain return values but output schema likely handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has low coverage (20%). Description mentions 'inferred audience, description, and tone' but does not explain title or token parameters in detail. Partially compensates but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a content project' and elaborates that it infers config, discovers sources, and gathers/ranks stories. This distinguishes it from siblings like update_project or get_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Best called after the inferred audience, description, and tone have been confirmed with the user', providing clear when-to-use guidance. Does not mention alternatives but context makes it clear this is the creation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_delete_contentDelete contentADestructiveIdempotentInspect
Delete a piece of content and its hosted images.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| contentId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| deleted | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and idempotent hints. The description adds value by stating that hosted images are also deleted, providing extra behavioral context beyond the annotations. No contradictions.
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 sentence that clearly conveys the purpose without any extraneous words. It is front-loaded and 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?
The tool has an output schema and annotations covering key behaviors. The description is sufficient for a delete operation, though it could mention irreversibility, but the destructiveHint annotation already implies that. Mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (both parameters are described in the schema). The description adds no additional parameter-level information beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' and clearly identifies the resource as 'a piece of content and its hosted images'. This clearly distinguishes it from sibling tools like 'hide_story' or 'delete_project'.
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 on when to use this tool versus alternatives. For instance, there is no mention of when to use 'hide_story' instead for non-destructive actions. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_delete_projectDelete projectADestructiveIdempotentInspect
Permanently deletes a project and everything in it — its sources, stories, and content. Cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| projectId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| deleted | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and idempotentHint=true. The description reinforces these by stating 'permanently deletes' and 'cannot be undone', adding context about irreversibility and scope. It does not contradict annotations. However, it omits details like failure modes (e.g., invalid project ID) or permission checks.
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 sentence that is concise and front-loaded with the key action and consequence. No unnecessary words or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature, the description appropriately warns of permanence. The presence of an output schema reduces the need to explain return values. However, it lacks preconditions (e.g., project existence, required permissions) that would help the agent avoid errors. For a simple delete operation, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (token has detailed description, projectId has none). The tool description adds no parameter-level meaning, relying entirely on the schema. For the undocumented projectId parameter, the description provides no guidance on format or constraints beyond what the schema's pattern/format offer.
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 'Permanently deletes a project and everything in it — its sources, stories, and content. Cannot be undone' uses a specific verb ('deletes') and resource ('project'), and clarifies the scope ('everything in it'). It distinguishes this from sibling tools like 'delete_content' or 'remove_source' by focusing on project-level deletion.
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 no guidance on when to use this tool versus alternatives (e.g., 'delete_content' for partial deletion). There are no explicit usage scenarios or exclusions, leaving the agent to infer applicability solely from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_derive_contentDerive contentCInspect
Transform an existing piece into another format (e.g. newsletter → tweet). No fetching; reuses the source stories and topic.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | ||
| tieIn | No | ||
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| fromContentId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| topic | Yes | |
| content | Yes | The generated content. Fields present depend on `type`. |
| summary | Yes | |
| contentId | Yes | |
| publicUrl | Yes | |
| storyCount | Yes | |
| imagesHosted | Yes | |
| creditsCharged | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With all annotations set to false, the description bears full responsibility for behavioral disclosure. It says 'Transform' and 'No fetching' but does not clarify side effects (e.g., whether original content is modified, if new content is created, or authorization/rate limits). This is insufficient for a potentially destructive operation.
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 that front-load purpose and add a constraint. Every sentence serves a purpose with no redundancy.
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?
Despite having an output schema, the description fails to explain the 'tieIn' parameter and does not specify behavior for non-existent input or error cases. With 4 parameters and low schema coverage, the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only 'token' has description). The description adds meaning for 'fromContentId' (input piece) and 'type' (output format) but ignores 'tieIn'. It partially compensates but not enough given low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool transforms an existing piece into another format with an example (newsletter to X). It specifies verb 'Transform' and resource 'existing piece'. While it doesn't explicitly differentiate from siblings like 'generate_content', the 'No fetching' clause provides implicit distinction.
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 context on when to use ('reuses the source stories and topic') but does not explicitly state when not to use or mention alternatives. It implies usage for format conversion but lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_expand_coverageExpand coverageAInspect
Broadens a project's coverage: expands the relevance criteria (when needed), finds more sources across news, the web, and the relevant social platforms, and fetches them inline. Applies on a topic_unavailable, no_stories, or low-coverage signal. May return warming: true with retryAfterMs (~60s), meaning the newly gathered stories are still landing. An out-of-scope focus requires confirmedByUser: true; without it, it returns a confirmation_required error. No credits are charged.
| Name | Required | Description | Default |
|---|---|---|---|
| focus | No | The topic to get more on (e.g. "League of Legends"). Omit to broaden the whole project. | |
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| projectId | Yes | ||
| addAsCriteria | No | Also append an in-scope `focus` as a standing relevance criterion (out-of-scope, confirmed foci are added automatically). | |
| confirmedByUser | No | Set true once the user has agreed to widen the project to an out-of-scope `focus`. |
Output Schema
| Name | Required | Description |
|---|---|---|
| _note | No | One-time note — e.g. a freshly issued demo token to save to durable memory and reuse. |
| warming | Yes | |
| retryAfterMs | Yes | |
| sourcesAdded | Yes | |
| storiesAdded | Yes | |
| criteriaAdded | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description adds valuable behavioral details: warming with retryAfterMs, the need for confirmedByUser for out-of-scope focus, and that no credits are charged. 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 concise yet comprehensive, covering all key aspects in a single paragraph without redundancy. 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?
Given the tool's complexity and available output schema, the description covers all necessary aspects: trigger conditions, warming behavior, token handling, parameter semantics, and error cases. It is complete for an agent to use 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?
With 80% schema description coverage, the baseline is 3. The description adds significant meaning: explains when to omit focus, token reuse on subsequent calls, effect of addAsCriteria, and purpose of confirmedByUser. This adds clarity 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 the tool's purpose: broadening a project's coverage by expanding relevance criteria and finding more sources. It specifies the trigger signals (topic_unavailable, no_stories, low-coverage) which distinguishes it from sibling tools like betterpost_create_project or betterpost_get_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on when to use the tool: upon low-coverage signals. It also explains the behavior with warming and out-of-scope focus requiring confirmedByUser. However, it does not explicitly list when not to use or name alternative tools, though the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_generate_contentGenerate contentAInspect
Generate a new piece of content for a project from its timely, relevant stories. Fast in steady state. Charges credits on success only. If you pass a topic the project has no stories about, this returns a topic_unavailable error (no charge) carrying an inScope flag and next steps — it never silently writes an off-topic piece.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Output format. 'x' and 'bluesky' are generated as a single post or, more often, a short numbered thread of connected posts (multiple tweets) when there is enough to say — this is the default for those channels. 'blog', 'newsletter', and 'linkedin' are one piece. | |
| reuse | No | Reuse the most recent topic. | |
| tieIn | No | A product/service to weave in. | |
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| topic | No | Steer the piece to a specific topic. Generation only writes from stories actually about it. If none exist yet, it returns topic_unavailable (no charge) with an inScope flag: inScope:true means the topic fits the project and betterpost_expand_coverage can gather it, while inScope:false means it is outside the project scope so expanding to it requires the user's confirmation. | |
| projectId | Yes | ||
| wordLimit | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| _note | No | One-time note — e.g. a freshly issued demo token to save to durable memory and reuse. |
| topic | Yes | |
| content | Yes | The generated content. Fields present depend on `type`. |
| summary | Yes | |
| contentId | Yes | |
| publicUrl | Yes | |
| storyCount | Yes | |
| imagesHosted | Yes | |
| creditsCharged | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes that it charges credits on success only, returns topic_unavailable error with inScope flag, and never silently writes off-topic content. Annotations (readOnlyHint=false, etc.) are consistent and description adds valuable context beyond 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?
Concise paragraph with front-loaded main purpose. Could be slightly improved with bullet points or sections, but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers error handling, charging behavior, topic steering, and alternatives. Output schema exists, so return values not needed. Comprehensive for a 7-param 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?
Adds meaningful details beyond schema for parameters like type (mentioning default thread behavior for x/bluesky), token (reuse and first call), and topic (inScope flag and expand_coverage). Schema coverage is 71% but description compensates well.
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 it generates content for a project from timely stories, lists output formats (blog, newsletter, linkedin, x, bluesky), and distinguishes from sibling tools like derive_content and delete_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (generate content), mentions alternative betterpost_expand_coverage for topic_unavailable errors, and explains error conditions and next steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_get_contentGet contentARead-onlyInspect
Fetch one piece of content in full.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| contentId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| type | Yes | |
| content | Yes | The generated content. Fields present depend on `type`. |
| summary | Yes | |
| topicId | Yes | |
| createdAt | Yes | ISO 8601 datetime string |
| projectId | Yes | |
| publicUrl | Yes | |
| wordLimit | Yes | |
| storyCount | Yes | |
| derivedFromContentId | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, making safety clear. The description adds 'in full' but no other behavioral details (e.g., error handling, required auth). No contradictions.
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?
Single sentence, no extraneous information. Every word serves a purpose: 'Fetch' (action), 'one piece' (uniqueness), 'in full' (completeness).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description is somewhat adequate but lacks context like where the contentId comes from (e.g., a prior list) and token reuse expectations. It is minimally sufficient for a simple fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the input parameters (contentId, token). The schema description covers token only, leaving contentId undocumented. With 50% schema coverage, the description should add meaning but does not.
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 'Fetch one piece of content in full' uses a clear verb (Fetch) and specifies the resource (one piece of content). It distinguishes from the sibling 'list_content' which implies multiple items, and 'in full' suggests comprehensive return.
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 when-not-to-use alternatives. The tool is straightforward for fetching a specific content item, but no guidance is given compared to siblings like derive or generate content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_get_projectGet projectARead-onlyInspect
Returns one project with its relevance criteria (each with an id, so a criterion can be targeted for removal via betterpost_update_project).
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| projectId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| tone | Yes | |
| title | Yes | |
| status | Yes | |
| audience | Yes | |
| criteria | Yes | |
| industry | Yes | |
| timezone | Yes | |
| createdAt | Yes | ISO 8601 datetime string |
| updatedAt | Yes | ISO 8601 datetime string |
| hasXSource | Yes | |
| description | Yes | |
| maxStoryAgeDays | Yes | |
| additionalInstructions | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds context about returning criteria with IDs, but does not disclose additional behavioral traits. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single sentence front-loaded with the main purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (not shown), the description is adequately complete for a simple get tool, highlighting the criteria IDs which is useful for downstream updates.
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 description adds no information about parameters. Schema coverage is 50% (token described, projectId not), and the description does not compensate for the undocumented projectId 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 clearly states the tool returns one project with relevance criteria, each having an ID, which is specific and distinguishes it from siblings like list_projects or get_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage by noting the criteria IDs can be used for removal via betterpost_update_project, but does not explicitly state when to use this tool versus alternatives like list_projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_get_settingsGet settingsARead-onlyInspect
Returns a project's per-content-type settings (wordLimit and additionalInstructions for each channel).
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| projectId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| contentTypeSettings | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds detail on the specific settings returned (wordLimit, additionalInstructions), which is useful beyond annotations. However, it doesn't disclose authentication needs or other behavioral traits.
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, concise sentence that front-loads the verb and resource, clearly stating what the tool does with no unnecessary words. Every element 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?
Given the tool's low complexity, output schema presence, and annotations, the description is mostly complete. It specifies the returned fields, which is sufficient, but omits mentioning the required projectId parameter explicitly.
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 50% (token described, projectId not). The description does not mention either parameter, leaving the agent to infer the need for a projectId from context. It fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a project's per-content-type settings, specifying 'wordLimit' and 'additionalInstructions' per channel. It distinguishes from siblings like 'get_project' (project-level settings) and 'get_content' (individual content).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. While it's implied for reading settings, there is no mention of when not to use it or how it differs from 'update_settings' or other read tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_get_usageGet usageARead-onlyInspect
Demo generations remaining, or paid credit balance + recent spend.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. |
Output Schema
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| _note | No | One-time note — e.g. a freshly issued demo token to save to durable memory and reuse. |
| frozen | No | |
| creditBalance | No | |
| recentSpendUsd | No | |
| generationsUsed | No | |
| generationsRemaining | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to reiterate safety. It adds context about demo vs. paid, but beyond that, no additional behavioral detail is provided.
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, concise sentence that front-loads the key information. No wasted words or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 optional parameter, output schema exists), the description covers all necessary context: what it returns for demo vs. paid users. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes the token parameter in detail. The description adds no further meaning for the 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 clearly states it retrieves usage information: 'Demo generations remaining, or paid credit balance + recent spend.' It uniquely identifies the tool's purpose among siblings, none of which relate to usage.
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?
While no explicit when-to-use guidance is given, the description implies usage for checking remaining generations or balance. The sibling tools are distinct, so no confusion arises. However, could benefit from mentioning it should be called before generation to avoid overage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_hide_storyHide storyAIdempotentInspect
Hides a story so generation ignores it. Reversible with unhide_story.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| storyId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| hidden | Yes | |
| storyId | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false, indicating safe retry and non-destructive action. The description adds that the hide is reversible, which is valuable behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys purpose and reversibility. It is front-loaded and contains no unnecessary 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 simple toggle action with an output schema (not shown), the description covers the core behavior but lacks details on what 'ignores' means operationally, return values, or any prerequisites. It is minimally adequate.
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 50% (token param described, storyId not). The description adds no parameter meaning beyond the schema, so it does not compensate for the missing storyId description. Baseline 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?
Description clearly states the tool hides a story so generation ignores it, using a specific verb and resource. It also mentions reversibility with the sibling tool, distinguishing it from unhide_story.
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 use when generation should ignore a story and points to the alternative for reversal, but lacks explicit when-to-use or when-not-to-use guidance. No conditions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_list_contentList contentARead-onlyInspect
List a project's content (summaries + shareable publicUrl links).
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| projectId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| content | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's burden is lower. It adds no further behavioral context (e.g., auth requirements, rate limits). The description is adequate but not enriched.
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, focused sentence (11 words) that front-loads the action and output. Every word earns its place, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description need not detail return values. It covers the key output elements (summaries, publicUrl links). However, it omits information about pagination or filtering, which could be relevant for a list tool. Still, it is largely complete for its purpose.
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 50% (token has a detailed description in schema, projectId has none). The tool description mentions 'a project' but does not elaborate on projectId semantics beyond the schema. The parameter token is well-described in schema, so the description adds minimal value.
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 verb 'List' and the resource 'a project's content', specifying the output includes 'summaries + shareable `publicUrl` links'. This distinguishes it from sibling tools like `betterpost_get_content` (single item) and `betterpost_delete_content`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by naming the action, but it does not explicitly state when to use this tool over alternatives, nor does it provide when-not scenarios or prerequisites. Minimal guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_list_projectsList projectsARead-onlyInspect
Returns your projects, each with its relevance criteria (with ids) that define what counts as on-topic.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. |
Output Schema
| Name | Required | Description |
|---|---|---|
| _note | No | One-time note — e.g. a freshly issued demo token to save to durable memory and reuse. |
| projects | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds value by mentioning that each project includes relevance criteria with IDs, which is behavioral context beyond annotations. No contradictions.
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 efficiently communicates the tool's function without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 param, output schema exists), the description covers the essential purpose and return content. No missing information that would hinder 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?
Schema coverage is 100% with a detailed description for the 'token' parameter. The tool description does not add any additional meaning about parameters beyond the schema, so 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 clearly states the tool returns projects and specifies the relevance criteria included. It distinguishes from siblings like 'betterpost_get_project' (single project) by implying a list of all projects. Verb 'returns' is specific and resource is clear.
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 on when to use this tool versus alternatives, such as when to use 'betterpost_get_project' for a single project. No explicit when-not-to-use or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_list_sourcesList sourcesARead-onlyInspect
Returns one slimmed page of a project's sources plus project-wide total and counts (ok/failing/disabled/pending, and byType). Page with limit (default 50) and offset, following the returned nextOffset until it is null.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max sources to return (default 50). | |
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| offset | No | Number of sources to skip; use the returned nextOffset to page. | |
| projectId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| limit | Yes | |
| total | Yes | |
| counts | Yes | |
| offset | Yes | |
| sources | Yes | |
| returned | Yes | |
| nextOffset | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by explaining the exact return data (slimmed page with total and counts) and pagination flow (use nextOffset until null). This adds significant behavioral context to the readOnlyHint=true annotation.
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, front-loaded with the main purpose, and every sentence adds essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (pagination, aggregated counts), existing annotations, and output schema, the description adequately covers what an agent needs to know to use the tool correctly, including how to iterate through pages.
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% (all parameters described), so baseline is 3. The description adds value by mentioning default limit (50) and the pagination technique, which helps the agent understand parameter usage beyond schema descriptions.
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 verb "Returns" and the resource "project's sources", and it distinguishes itself from sibling tools like betterpost_add_source or betterpost_remove_source by specifying it is a list operation with pagination and summary counts.
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 explains how to paginate using limit, offset, and nextOffset, providing clear usage guidance. However, it does not explicitly tell when to use this tool versus other list tools (e.g., betterpost_list_content), though the context is implied by the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_list_storiesList storiesARead-onlyInspect
Returns a project's gathered stories, each with title, url, summary, relevancy, publicationDate, and isManual/isHidden flags. Pass includeHidden to include hidden ones.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| projectId | Yes | ||
| includeHidden | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| stories | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by detailing the output fields and the includeHidden option. No contradictions. It does not mention rate limits or pagination, but these are not critical for a read-only list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and includes specific field names. Every word adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to fully detail return values but still lists key fields. It mentions the optional parameter and the nature of the output. Could improve by noting that projectId is required, but overall sufficient for a list 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 low (33%). The description adds meaning for includeHidden but not for projectId. The token parameter is well-described in schema. Given low coverage, more compensation would be ideal; current addition is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a project's gathered stories and lists specific fields. It distinguishes from siblings like betterpost_add_story and betterpost_list_content by specifying the resource type (stories) and the gathering aspect.
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 tells when to use the includeHidden parameter. However, it does not explicitly compare with sibling tools or provide when-not-to-use guidance. The usage is clear for a list operation, but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_remove_sourceRemove sourceADestructiveIdempotentInspect
Removes a source from a project. Its already-gathered stories stay; the source is no longer fetched.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| sourceId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| removed | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and idempotent; the description adds the important nuance that stories are not removed, providing context beyond the structured fields. No contradictions.
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, each carrying essential information, no redundancy or 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?
Covers key behavioral context (stories stay) and effect (no longer fetched). Output schema exists, so return values are covered. Could mention idempotency, but annotation handles that.
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 50% (only token has description), yet the tool description fails to describe sourceId or clarify how token relates to removal. The description adds no parameter information, leaving the agent under-informed.
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 action ('Removes a source from a project') and specifies a key behavioral distinction ('stories stay; no longer fetched'), making it distinct from siblings like delete_content or hide_story.
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 when to use (stop fetching a source but keep stories) but does not explicitly compare with alternatives like delete_content or hide_story, or state prerequisites like ownership.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_suggest_topicsSuggest topicsAInspect
Clusters a project's current stories into a few candidate angles — each with a label, how many stories back it, and example headlines — and warms the project (gathers and ranks fresh stories) in the process. Returns topics you can offer the user before generate_content.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| count | No | ||
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| projectId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| topics | Yes | |
| projectId | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and openWorldHint=true. Description adds specific behavioral detail: 'warms the project (gathers and ranks fresh stories)', which goes beyond annotations. No contradiction.
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 concise sentences, front-loaded with action, no fluff. 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?
With output schema present, description covers clustering process, output format, side effect (warming), and usage timing. Lacks explicit parameter guidance but otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only token described). Description does not explain type (platform enum) or count (number of topics), leaving ambiguity. Parameter meaning must be inferred.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool clusters stories into candidate angles with labels, story count, and headlines, and returns topics to offer before generate_content. This distinguishes it from siblings like generate_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage before generate_content ('offer the user before generate_content') but provides no explicit when-not-to-use or alternatives. Context is clear but lacks exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_unhide_storyUnhide storyAIdempotentInspect
Unhides a previously hidden story so generation can use it again.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| storyId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| hidden | Yes | |
| storyId | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true and destructiveHint=false. The description adds that it 'unhides' a story, reversing the hide action, and that it enables generation again. This provides context beyond annotations, though it does not detail side effects or limits.
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 sentence that is front-loaded with the action and result. No extraneous words; every part 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?
Given the simplicity of the tool (unhide story) and the presence of an output schema, the description is mostly complete. However, it does not mention that a token is required (even though token is in the schema), which could be important for context.
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 has 50% coverage (token is described, storyId has only format). The tool description does not mention any parameters or add meaning beyond the schema. It fails to compensate for the missing description of storyId, leaving ambiguity about the parameter's purpose.
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 action ('unhides') and the resource ('previously hidden story'), with a specific outcome ('so generation can use it again'). It effectively distinguishes from sibling 'hide_story' by reversing that operation.
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 when to use this tool (when a story is hidden and needs to be reused), but does not explicitly state when not to use it or mention alternatives. Given the sibling 'hide_story', the context is clear, but no exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
betterpost_update_projectUpdate projectAInspect
Updates a project's title, audience, description, tone, freshness window, timezone, or relevance criteria, and returns the updated project with its criteria. Changing title/audience/description re-derives the relevance criteria (replace-all), which broadens or narrows what counts as on-topic. To edit criteria incrementally instead, pass patch.addCriteria (texts to append) and/or patch.removeCriteria (criterion ids from get_project/list_projects). Dates default to US Eastern unless a timezone (an IANA name like "America/New_York") is set.
| Name | Required | Description | Default |
|---|---|---|---|
| patch | No | Partial update: EVERY field is optional — include only the fields you want to change and omit the rest (an omitted field is left untouched; there are no required patch fields). Passing an empty object or omitting `patch` entirely is a no-op. Fields: title, audience, description, tone, maxStoryAgeDays, additionalInstructions, timezone, addCriteria, removeCriteria. | |
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| projectId | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| tone | Yes | |
| title | Yes | |
| status | Yes | |
| audience | Yes | |
| criteria | Yes | |
| industry | Yes | |
| timezone | Yes | |
| createdAt | Yes | ISO 8601 datetime string |
| updatedAt | Yes | ISO 8601 datetime string |
| hasXSource | Yes | |
| description | Yes | |
| maxStoryAgeDays | Yes | |
| additionalInstructions | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (all false), the description discloses key behaviors: updating title/audience/description re-derives relevance criteria, empty patch is a no-op, dates default to US Eastern, and maxStoryAgeDays affects story freshness. This adds significant value.
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 paragraph that front-loads the main purpose, then adds details. It is informative but slightly dense; could be split into bullet points for readability, but no redundancy.
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 3 parameters, nested objects, and output schema, the description covers all aspects: updatable fields, effects, incremental editing, timezone defaults, token reuse, and maxStoryAgeDays meaning. Very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (67%), but the description adds crucial meaning: patch fields are optional, omission leaves field untouched, addCriteria appends without replacement, removeCriteria requires UUIDs from get_project/list_projects, and maxStoryAgeDays has optimal range and effects. Token explanation is also provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates specific fields (title, audience, description, etc.) and returns the updated project. It distinguishes from sibling tools like create_project and delete_project by detailing what is updated and how incremental criteria editing works.
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 context on when to use incremental vs. replace-all updates via patch.addCriteria/removeCriteria. It also mentions default timezone and the effect of omitting patch. However, it does not explicitly 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.
betterpost_update_settingsUpdate settingsAIdempotentInspect
Patches one content type's wordLimit and/or additionalInstructions (free-form writing guidance for that type; pass an empty string to clear it). Project-wide preferences (title/audience/tone, project-wide additionalInstructions) live on betterpost_update_project.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | ||
| token | No | Your saved BetterPost token from a prior call (demo `bp_demo_…` or paid `bp_live_…`). Reuse the same token on every call and across conversations; omit only on the very first call to be issued a free demo token. Paid users may instead pass the key in the server URL (?key=…) or an Authorization: Bearer header. | |
| projectId | Yes | ||
| wordLimit | No | ||
| additionalInstructions | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| updated | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (modification), destructiveHint=false, and idempotentHint=true. The description adds behavioral details beyond these, such as the 'patch' semantics (partial update) and the specific behavior of passing an empty string to clear additionalInstructions. This adds value without contradicting 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 extremely concise, consisting of two sentences. The first sentence states the core functionality, and the second provides critical differentiation from a sibling tool. Every word 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?
Given the tool's moderate complexity (5 params, 2 required, output schema exists), the description covers the key aspects: what is patched, how to clear a field, and distinction from project-wide updates. It does not mention error conditions or interplay with other parameters, but the output schema likely handles return values.
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 low (20%), but the description explains the purpose of wordLimit (implicitly a word limit) and additionalInstructions (free-form guidance, clear with empty string). It does not explain the type enum values or the format/constraints of optional parameters, relying somewhat on the schema. This provides moderate added meaning.
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 it patches one content type's wordLimit and/or additionalInstructions, with a specific verb ('Patches') and resource ('one content type's settings'). It also explicitly distinguishes itself from sibling betterpost_update_project, which handles project-wide preferences.
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 to use this tool vs. the sibling betterpost_update_project by stating that project-wide preferences live on that tool. However, it does not explicitly mention prerequisites (e.g., project must exist) or when not to use it (e.g., for reading settings, use betterpost_get_settings).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
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
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.
Discussions
No comments yet. Be the first to start the discussion!