BetterPost

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behavioral traits: the fetch happens immediately (bounded by a few seconds), returns 'storiesAdded' immediately, may return 'fetched:false' if still fetching, and doubles as manual import or recurring search. This adds significant context beyond the annotations, which already indicate readOnlyHint=false and openWorldHint=true. The description does not mention rate limits or other side effects, but the openWorldHint covers unknowns.

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 long, covering purpose, behavior, and usage patterns. It is efficient but the first sentence is quite dense, mixing behavior and return values. Could be slightly restructured for clarity, but overall it's concise and front-loads the key action.

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 (4 parameters, two distinct use cases) and the presence of an output schema (reducing need to document return types), the description is complete. It explains the fetching behavior, the different modes (manual vs search), and ties to the next step (generate_content). No gaps remain.

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 meaning beyond the input schema. It explains that 'value' can be a URL or search terms, and 'type' determines the source kind or search type. The schema only describes 'type' but not 'value' or 'projectId'. The description compensates for the low schema coverage (25%) by clearly explaining both parameters' roles. 'name' is optional and not covered, but it's self-explanatory.

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 adds a source to a project and fetches it immediately. It distinguishes between manual URL import and recurring keyword search, which are distinct use cases. The verb 'adds' and resource 'source' are specific, and the description differentiates from siblings like 'remove_source' or 'list_sources' by detailing the fetching behavior and return values.

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 for immediate fetching so that 'generate_content' can use it. It provides guidance on how to use it for both manual import and search creation. However, it does not explicitly state when not to use it or compare to other tools like 'betterpost_add_story' or 'betterpost_suggest_topics'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral context beyond the annotations: it indicates the story is 'pinned' and 'flagged is_manual', and that the import is from a URL. Annotations already mark it as non-read-only, so the write nature is consistent. The description provides useful additional traits 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 a single sentence that is concise and front-loaded. It communicates the core purpose without any wasted words or unnecessary details. It earns its place by being direct and informative.

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 4 parameters (2 required) and no schema descriptions, the description is somewhat incomplete. It does not clarify behavior in edge cases (e.g., duplicate URL, project existence) or mention output. However, an output schema exists, reducing the need to explain return values. Still, more context on prerequisites and behavior would improve completeness.

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%, so the description must compensate. While it hints at the 'url' parameter (import from URL), it does not explain the meaning or usage of 'projectId', 'title', or 'summary'. These are left to the agent to infer, which is insufficient given the lack of 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 'imports', the resource 'story', and the method 'from its URL'. It also explains the effects (pinned relevance, flagged is_manual) and the purpose (so generation can draw on it). This distinguishes it from sibling tools like betterpost_list_stories or betterpost_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 the tool: when you have a story you read about and want to manually import it. However, it does not explicitly state when not to use it or mention alternatives among the 21 sibling tools. The context is clear but lacks exclusionary guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and openWorldHint=true. The description adds valuable context: 'Slow, one-shot: infers config... discovers sources... gathers/ranks...' This explains the heavy, non-idempotent behavior. 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?

Two sentences with no fluff. The first sentence states the core action and behavior; the second provides usage guidance. Key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the tool's process (slow, one-shot, inference, discovery, ranking) and when to call it. An output schema exists, so return values are covered. However, it does not mention error conditions or prerequisites beyond user confirmation, which 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 has 4 parameters with 0% description coverage, so the description must compensate. It mentions 'inferred audience, description, and tone,' linking these to the config, but does not detail each parameter's purpose or format. This adds minimal value beyond the parameter names.

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 ('Create') and resource ('content project'). It distinguishes from sibling tools like update_project and delete_project by emphasizing it's a one-shot operation that infers config and discovers sources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'Best called after the inferred audience, description, and tone have been confirmed with the user.' This tells the agent when to use it and implies not to use it prematurely. No alternatives are named, but 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds value by specifying that hosted images are also deleted, which is a key behavioral trait not captured by annotations. There is no contradiction. The description could be improved by noting any recovery limitations.

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 that front-loads the action and includes an important side effect. Every word contributes meaning with 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?

For a simple, destructive tool with one parameter and an existing output schema, the description covers the primary effect and side effect. It lacks mention of whether the deletion is reversible or any confirmation step, but the output schema likely addresses return values. The description is minimally 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?

The input schema has 0% description coverage and only one parameter 'contentId'. The tool description does not describe the parameter beyond implying it identifies the content. No format, source, or example is provided, leaving the agent to infer meaning from the parameter name and schema pattern.

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 'Delete' and the resource 'a piece of content and its hosted images'. It distinguishes from sibling tools like betterpost_delete_project by specifying it is content-specific, and adds valuable context about associated images being deleted.

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 explicit guidance on when to use this tool versus alternatives (e.g., betterpost_delete_project for projects), nor does it mention prerequisites or conditions. The side effect of deleting hosted images is stated but not framed as a usage consideration.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark destructiveHint=true and idempotentHint=true. The description adds value by detailing the cascading deletion (sources, stories, content) and reinforcing irreversibility. 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?

Single sentence, front-loaded with the action and scope. No wasted 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 output schema exists and the tool is straightforward (one param, clear destructive effect), the description covers all essential context: what gets deleted, permanence, and scope. 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?

With 0% schema description coverage, the description carries full burden for the single parameter projectId. It implicitly identifies the project to delete but adds no detail about its format, source, or constraints beyond what the schema's format and pattern already provide.

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 'deletes', the resource 'project', and specifies the scope 'and everything in it — its sources, stories, and content'. This distinguishes it from sibling tools like delete_content that only remove 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 explicitly notes the permanence ('Cannot be undone'), implying caution. However, it does not directly compare to siblings like delete_content or update_project to guide selection. The context is clear but lacks explicit exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that the tool does not fetch new data and reuses source stories and topic, providing context beyond annotations. However, it does not clarify whether the transformation creates a new content item or updates the existing one, leaving some ambiguity.

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 with no extraneous information. The key points are front-loaded, making it easy to scan.

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?

While an output schema likely covers return values, the description lacks detail on what 'transform' produces (e.g., a new content item?) and does not explain parameters. This leaves gaps for agent understanding.

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 0%, yet the description offers no explanation of the three parameters (type, fromContentId, tieIn). The enum for type is hinted at by the example but not defined. This is a critical failing for usability.

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?

Clearly states the tool transforms an existing piece into another format, with a specific example (newsletter → tweet). This distinguishes it from sibling tools like betterpost_generate_content (which likely creates from scratch) and betterpost_humanize (which rewrites without format change).

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?

Describes context ('No fetching; reuses the source stories and topic'), implying it should be used when you have existing content to reformat. Lacks explicit when-not-to-use or alternatives, but the example and sibling tool names provide reasonable guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant behavioral context beyond annotations: it explains the warming mechanism with retryAfterMs, that no credits are charged, and the confirmation_required error for out-of-scope focus. This complements the annotations (readOnlyHint=false, openWorldHint=true) without 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?

The description is concise (5 sentences) and front-loaded with the primary action. Every sentence provides necessary information: what it does, when to use, behavioral notes (warming, errors, credits). No filler or 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?

The description covers key aspects: purpose, usage signals, parameter behavior, errors, and cost. With an output schema present, return values need no explanation. Minor gap: does not explicitly state that expansion adds sources/stories to the project, but it's implied from 'broadens coverage' and 'fetches them inline'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has high coverage (100% with descriptions). The description adds value by explaining usage nuances: 'Omit to broaden the whole project' for focus, and the automatic addition of out-of-scope confirmed foci for addAsCriteria. This enhances 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 the tool broadens a project's coverage by expanding relevance criteria, finding sources, and fetching them inline. It specifies conditions for use (topic_unavailable, no_stories, low-coverage signal), distinguishing it from siblings like betterpost_add_source which add individual sources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to apply the tool (on topic_unavailable, no_stories, or low-coverage signal). It also provides context for out-of-scope focus requiring confirmedByUser. However, it does not explicitly mention when to use alternatives, though the conditions are clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant behavioral details beyond annotations: fast performance, credit charging on success only, and error behavior (topic_unavailable with inScope flag, never silent off-topic generation). Annotations only indicate read/write, idempotence, and destructiveness, which are consistent.

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 (three sentences), front-loads the primary purpose, and includes only necessary behavioral and billing details 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?

The description covers purpose, billing, and error handling adequately. It lacks explicit prerequisites (e.g., need stories in project) and does not differentiate from sibling tools, but the presence of an output schema reduces the need to describe 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?

The input schema already provides rich descriptions for all parameters, including error handling for the topic parameter. The tool description repeats this information without adding new parameter-specific insights. With high schema coverage, the description adds minimal value to parameter understanding.

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 'Generate a new piece of content for a project from its timely, relevant stories,' which is a specific verb+resource combination. It distinguishes from siblings like 'derive_content' (likely for refining) and 'expand_coverage' (for gathering stories).

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 clarifies when to use the tool (to generate content from stories) and explains error handling for missing topics. However, it does not explicitly compare to sibling tools or state when not to use it, missing some guidance for alternative selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true and destructiveHint=false, so the read-only nature is clear. The description adds 'in full' but no further behavioral details (e.g., response size, errors). Annotations carry most of the burden; description is adequate but minimal.

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?

Extremely concise: one sentence with no filler. Information is front-loaded and every word earns its place. Ideal for quick scanning.

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 fetch-by-ID tool with an output schema, the description covers the essential purpose. Could mention error handling or behavior if content not found, but not critical for basic understanding.

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 0%, so the description must compensate for the undocumented parameter. The description does not explain contentId beyond its name and type in the schema. It adds no meaning like format expectation or relationship to other tools.

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' clearly states the verb (fetch), resource (content), and scope (one, in full). It distinguishes from siblings like list_content (multiple) and delete_content (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?

No guidance on when to use this tool versus alternatives (e.g., list_content for multiple). No prerequisites or context for when fetching is appropriate. The description is purely declarative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds that the tool returns criteria with IDs, which is useful behavioral context. However, it does not discuss error handling, authorization needs, or rate 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?

The description is a single, compact sentence that immediately conveys the tool's core action and key return value. 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?

Given the output schema exists, the description could afford to be brief. However, it omits guidance on the parameter (projectId) and does not mention any prerequisites or error conditions. For a simple get tool, it is mostly adequate but leaves a gap for parameter semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage for the sole parameter (projectId), and the description does not explain what the parameter represents or how to obtain it. The parameter name is partially self-explanatory, but the description should at least clarify its purpose, which it fails to do.

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 single project and highlights the relevance criteria with IDs, which is specific and distinguishes it from list_projects and update_project. The verb 'Returns' is clear and the resource 'project' is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly suggests a use case: obtaining criteria IDs for removal via betterpost_update_project. However, it does not explicitly state when to use this tool versus alternatives like betterpost_list_projects or betterpost_get_content, nor does it mention prerequisites or limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description aligns by stating 'Returns', but adds no extra behavioral context beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the action and result, with no extraneous 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 the simple tool with one parameter, rich annotations, and an output schema (not shown but present), the description is largely complete. It could mention the required projectId but is 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 description does not explain the single parameter (projectId). With 0% schema description coverage, the description should compensate but fails to add meaning beyond the schema's format/pattern.

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 per-content-type settings', and specifies the exact fields (wordLimit and additionalInstructions). It distinguishes from sibling tools like update_settings which write, making it easy to identify.

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 for retrieving settings, but does not explicitly state when to use it versus alternatives like update_settings, nor does it mention any prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety profile is clear. The description adds value by specifying the exact data fields returned, beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is clear and front-loaded. Every word is necessary, and there is no wasted text.

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 that an output schema exists, the description adequately explains what the tool returns. For a simple read operation with no parameters, this is 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?

There are no parameters, and schema coverage is 100%. With zero parameters, the baseline is 4, and the description adds meaning by listing the return fields, which is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool returns: credit balance, freeze state, and recent spend. It is specific and distinguishes from sibling tools like get_settings (which likely returns settings) and get_project (project details).

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 or when not to use alternatives. However, given the tool is a simple get with no parameters and sibling tools are for other resources, the usage context is somewhat implied but could be improved with direct statements.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds that the action is reversible, providing useful behavioral context beyond the 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?

The description is extremely concise (7 words) and front-loaded with the action. Every sentence serves a purpose: stating the action and noting reversibility.

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 parameter, no nested objects) and presence of an output schema, the description adequately covers the essential purpose and reversibility. It could add a bit more detail about the hiding mechanism, but it's sufficient for 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?

The input schema has one parameter (storyId) with 0% schema description coverage. The description does not mention the parameter at all, failing to add meaning beyond the schema. It should specify that storyId is required and what it represents.

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 'hides' and the resource 'story', and specifies the effect 'so generation ignores it'. It also distinguishes from the sibling 'unhide_story' by noting reversibility.

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 indicates when to use (to hide a story) and mentions the alternative for reversal (unhide_story). It does not explicitly state when not to use it, but 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate the tool is not read-only and not destructive. The description adds that the rewrite preserves meaning, facts, links, and format, and returns notes on changes. However, no additional behavioral traits beyond annotations are disclosed, and the mutation nature is already implied by 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 concise sentences: the first covers the core action and output, the second explains optional parameters. Every sentence adds value 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 has 4 parameters and an output schema, the description covers the essential purpose, output, and parameter usage. It does not repeat schema details like the required text parameter or max length, but the schema already handles that. Minor gap: no mention of the output format, but output schema exists.

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 covers 100% of parameters, but the description adds meaningful context: it explains that tone wins over project tone, and that projectId uses the project's tone and writing instructions. This enhances understanding beyond the schema's literal 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 tool rewrites text into a human voice, preserving meaning, facts, links, and format. It distinguishes itself from sibling tools by focusing on rewriting existing content rather than generating new content or deriving 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 explains when to use optional parameters (projectId for project tone, type for channel style, tone for direct override) but does not explicitly state when not to use the tool or compare it to alternatives. Some guidance is present, but exclusions are missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds that the tool returns summaries and publicUrl links, but does not mention other behavioral traits like pagination, ordering, or whether all content is listed. It does not contradict 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, front-loaded with the verb 'List'. It is concise with no extraneous information. However, it could be slightly more informative without losing conciseness.

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 (though not provided), the description may be somewhat complete. However, it lacks guidance on whether the list is ordered, paginated, or includes all content. For a listing tool with one parameter, it is adequate but not thorough.

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 only parameter (projectId) has no description in the input schema (0% coverage), and the tool description does not mention it. The agent is left to infer that projectId identifies the project. The description adds no meaning beyond the schema type and format.

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 'List a project's content' and specifies it returns summaries and publicUrl links. This distinguishes it from siblings like get_content (single item) and generate_content (creates). However, it could be more explicit about listing all content items, and does not differentiate from other list tools (e.g., list_projects) but those have different resources.

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 vs alternatives. With many sibling tools (e.g., get_content, generate_content, list_stories), the agent would benefit from hints about when to list content rather than retrieve or generate. No when-not or exclusion criteria provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as readOnlyHint=true and destructiveHint=false. The description adds value by specifying that projects include relevance criteria with ids, which is not evident from annotations alone.

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 core purpose and includes a key detail. No extraneous 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?

The tool has an output schema, zero parameters, and the description covers the essential purpose and a notable detail. For a simple list tool, it is fully 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?

The tool has 0 parameters, so no parameter documentation is needed. Schema description coverage is 100% (vacuous). Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('returns') and the resource ('your projects'), and adds specific detail about what each project includes (relevance criteria with ids). This distinguishes it from sibling tools like get_project (single project) or create_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?

The description implies when to use (when you need a list of projects with relevance criteria) but does not explicitly state when not to use or provide comparisons to alternatives like list_content.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and destructiveHint=false. Description adds that results are paginated, includes project-wide counts, and must follow nextOffset. No contradiction, adds useful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, no wasted words. First sentence states purpose and return structure, second explains pagination. Well 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?

Given output schema exists, description covers pagination, default limit, and return data outline. Could mention read-only nature but annotations already convey that. Adequate for a listing 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 meaning beyond schema: default limit value, offset usage described as 'skip and follow nextOffset'. ProjectId not described but is a required UUID; overall adds value with 67% schema 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?

Description clearly states it returns a slimmed page of sources with total and counts, using specific verbs and resource. Distinguishes from sibling tools like betterpost_add_source and betterpost_remove_source by listing sources rather than modifying them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear pagination instructions using limit, offset, and nextOffset. Mentions default limit (50). Lacks explicit when-not-to-use or alternatives, but context is sufficient for a list endpoint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare `readOnlyHint=true` and `destructiveHint=false`. The description adds the returned fields and a filter parameter, which provides some behavioral detail beyond annotations, but does not significantly enhance transparency.

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 with front-loaded verb and object. Every word adds value 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 tool's simplicity (2 parameters, read-only, output schema exists), the description covers the necessary context: what is returned, how to filter, and that it's per-project. Could mention pagination or sorting but not essential for basic use.

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%, but the description explains both parameters: `projectId` is implied by 'a project's', and `includeHidden` is explicitly described ('Pass includeHidden to include hidden ones'). This compensates for the lack of property 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 tool returns a project's gathered stories and lists specific fields (`title`, `url`, `summary`, etc.). It distinguishes from sibling tools like `betterpost_add_story` or `betterpost_hide_story` by focusing on listing.

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 a practical hint ('Pass includeHidden to include hidden ones') and implies the tool is for reading stories of a specific project. It does not explicitly state when not to use it, but the context is clear enough for a simple list operation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds value beyond annotations by specifying that existing stories are preserved and fetching stops. It aligns with the destructiveHint=true and idempotentHint=true 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, clear sentence with no wasted words. It is front-loaded with the action and quickly addresses the key behavioral nuance.

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 removal tool with one parameter and an output schema, the description adequately covers the effect. It does not mention error conditions or return values, but the presence of an output schema may offset the latter.

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 0% description coverage, and the tool description does not mention the single parameter 'sourceId' or its meaning. The agent must infer from the tool name and schema pattern, but no additional semantic context is 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 uses the specific verb 'removes' and identifies the resource 'source from a project,' which distinguishes it from sibling tools like betterpost_add_source. It further clarifies that existing stories are not removed, differentiating it from delete operations.

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 the description states the effect (stories stay, source no longer fetched), it does not explicitly provide when-to-use or when-not-to-use guidance. However, the context from sibling tool names and the clear behavioral outcome sufficiently imply usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses the side effect of 'warming' the project (gathering and ranking stories), consistent with readOnlyHint=false. Adds context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load the main action. Could be slightly more structured but functional.

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?

Describes output (topics with label, stories back, headlines) but leaves parameter details and side-effect implications unexplained. Adequate given output schema exists.

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?

No parameter descriptions; 0% schema coverage. Does not explain type, count, or projectId meaning despite having 3 parameters with 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?

Description clearly states it clusters stories into candidate angles and prepares topics for generate_content. Distinguishes itself from sibling generate_content by indicating it should be used before.

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 use before generate_content but lacks explicit guidance on when not to use or alternatives among many siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide idempotentHint=true and destructiveHint=false; the description adds context that the story is used by generation, which is valuable. 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?

Single sentence, 11 words, front-loaded verb, 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?

Sufficient for a simple operation with one parameter and output schema present. Lacks error handling details but covers essential purpose and effect.

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 adds value by linking the storyId parameter to 'previously hidden story', clarifying its required context.

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), the resource (story), and the effect (generation can use it again). It distinguishes from sibling 'betterpost_hide_story' by specifying reversal.

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 (to make a hidden story available for generation) but does not explicitly state when not to use or provide alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors beyond annotations: re-derivation of criteria on title/audience/description change, no-op for empty patch, timezone default. Annotations are all false (readOnlyHint, destructiveHint, etc.), and 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?

Single paragraph but well-organized: purpose first, then replace-all behavior, then incremental editing, then timezone default. Every sentence adds value, though slightly lengthy.

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 complexity (multi-mode update, side effects, optional fields) and presence of output schema, the description covers all essential aspects: two editing modes, no-op behavior, timezone handling, and link to get_project/list_projects for criteria ids.

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 meaning beyond schema: explains that timezone defaults to US Eastern, clarifies addCriteria/removeCriteria roles, and states omitted fields are unchanged. Schema already has descriptions for some fields, but the description provides context for how they interact.

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?

Clearly states 'Updates a project's title, audience, description, tone, freshness window, timezone, or relevance criteria, and returns the updated project with its criteria.' The verb 'updates' and resource 'project' are explicit, and the list of updatable fields distinguishes this from sibling tools like create_project 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?

Provides explicit guidance on when to use replace-all (when changing title/audience/description) vs incremental editing (using addCriteria/removeCriteria). Also notes date defaults. Does not explicitly state when not to use, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate idempotent and non-destructive behavior. The description adds behavioral context by specifying it is a patch operation (partial update) and explains how to clear additionalInstructions. There is 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 two sentences: the first defines the action and parameters, the second distinguishes from the sibling. It is concise, front-loaded, and 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 0% schema coverage and presence of output schema (not shown), the description compensates for some parameters but does not explain projectId. It also does not mention return values. The description is sufficient for basic use but lacks full completeness.

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 explains wordLimit and additionalInstructions but does not mention projectId or type explicitly. However, it implies type by saying 'one content type's'. Since schema coverage is 0%, the description should cover all parameters, but it misses projectId and type explanation, making it partially inadequate.

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 a content type's wordLimit and/or additionalInstructions, with a specific verb ('patches') and resource ('one content type's wordLimit and/or additionalInstructions'). It distinguishes itself from the sibling tool betterpost_update_project by noting that project-wide preferences live there.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use this tool (for per-content-type settings) and when not to use it (for project-wide preferences, use betterpost_update_project). It also provides guidance on clearing additionalInstructions by passing an empty string.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.