PostKing MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.1.7
Disambiguation3/5
Many tools have clearly distinct purposes, but several clusters overlap noticeably: the roadmap is served by three tools (seo_list_roadmap, seo_roadmap_get, get_seo_roadmap), side-page generation has both generate_side_page and seo_generate_side_page, and job monitoring is split between list_jobs, list_operations, and get_job. Detailed descriptions help, but an agent could easily misselect among these.
Naming Consistency3/5
Naming is widely mixed: some domains use prefixes consistently (seo_*, competitor_*, storyline_*), while others use plain verb_noun (list_posts, create_post). There are also bare verbs like health, whoami, logout, and inconsistent patterns like seo_roadmap_get vs get_seo_roadmap. All names are snake_case, but the lack of a uniform convention across domains creates friction.
Tool Count1/5
At 243 tools, this is an extreme mismatch for an MCP server. Even though it covers a wide range of marketing features, the sheer volume overwhelms the context and makes selection impractical. The calibration clearly marks 25+ as too many, and this far exceeds that.
Completeness4/5
The tool surface is remarkably comprehensive across content generation, SEO, blog management, landing pages, competitor analysis, and billing. For most resources there are create/read/update/delete operations, and async operations are well covered with polling and job tools. Minor gaps exist (e.g., no direct social account update, no publication-level get), but they are workable.
Average 4.3/5 across 225 of 243 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 29 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly identifies the mutating nature (removal) but does not disclose potential side effects, reversibility, or behavior when no visual is selected. The mention of 'editInVisualEditor' is a behavioral detail but is cryptic and incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but the second sentence introduces ambiguity about whether editInVisualEditor is a return value or a side effect. The structure is slightly disjointed, though the primary action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is incomplete. It does not explain what the tool returns, how to interpret the response, or under what conditions editInVisualEditor appears. The platform-specific behavior is mentioned but not elaborated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the baseline is 3. The description does not add additional parameter semantics; postId and platform are already adequately described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the primary action: removing a selected visual from a post for a specific platform. The second sentence about editInVisualEditor is tangential and slightly detracts from the core purpose, but the verb 'remove' distinguishes it from siblings like pick_post_visual or regenerate_post_visual.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as pick_post_visual or regenerate_post_visual. The description implies usage for removing a visual but provides no prerequisites, exclusions, or context about when clearing is appropriate versus other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of disclosing side effects, return behavior, and prerequisites. It only mentions the method and outcome, omitting whether the input is mutated, what the response contains, or if a brand context is required. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and purpose. Every word contributes value, with no redundancy or extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is too sparse to fully inform an agent. It lacks context about when to select this tool over similar siblings, what to expect as a response, or any operational constraints, making it incomplete for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters (text, brandId, platform), achieving 100% coverage. The tool description adds no extra meaning about how these parameters affect the output, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Apply LLM rewrite and BERT replacements') and a clear outcome ('reduce AI detection signals in text'). It distinguishes from generic rewriting by mentioning AI detection, but does not explicitly contrast with sibling tools like rewrite_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., rewrite_text, rewrite_with_voice). It implies usage 'when you want to reduce AI detection' but lacks explicit scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It only states the operation 'Rewrite text' and the voice profile requirement, but does not mention authentication, reversibility, rate limits, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero filler; it is front-loaded and communicates the core action. There is no redundant wording or unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and four parameters, the description is too thin for an agent to invoke correctly with confidence. Missing are the return value, the role of optional brandId/platform, default behavior, and how this tool differs from rewrite_text/humanize_text.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal meaning beyond restating 'voice profile' and 'text'; it does not clarify defaults like active brand for brandId or platform-specific behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb + resource: 'Rewrite text using a specific voice profile.' It clearly states the tool's function and the distinguishing voice-profile aspect, though it doesn't explicitly contrast with sibling rewrite_text/humanize_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like rewrite_text, humanize_text, or generate_text. There are no prerequisites, exclusions, or contextual hints for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavioral traits. It mentions the confirm:true requirement, which is a useful signal, but this is already present in the schema. It does not disclose that deletion is permanent, whether it cascades to side page versions, or any other side effects. For a destructive tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences. 'Delete a side page' clearly states the action, and 'Pass confirm: true to proceed' adds the one critical instruction. No wasted words, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description is under-specified. It lacks critical context such as permanence, effect on versions (especially since a sibling delete_side_page_version exists), and any post-deletion consequences. The description is insufficient to fully inform an agent about the tool's impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description only repeats the confirm requirement already described in the schema ('Must be true to confirm deletion') and adds no additional meaning for slug or sideKey beyond their schema descriptions. No new parameter semantics are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' and the resource 'side page', making the tool's purpose immediately clear. It distinguishes from sibling tools like edit_side_page, view_side_page, and delete_side_page_version by indicating it deletes the entire side page rather than a version or property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. Sibling tools include delete_side_page_version and restore_side_page_version, and the description does not clarify that this tool is for permanently deleting the entire page, nor does it mention any prerequisites or contexts (e.g., unpublishing first). This leaves the agent without explicit selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It only says 'Create a new category' and does not mention side effects, permission requirements, duplicate handling, or return value. This is minimal for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with clear subject and object. It wastes no words and is appropriately sized for the tool's simple purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with no output schema and no annotations, the description plus schema is mostly adequate, but it lacks behavioral context such as what happens on duplicate slugs or what the response contains. It is sufficient but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for 4 of 5 parameters (80% coverage), so the baseline is 3. The description adds no extra meaning to the parameters; it does not clarify the 'description' field or any parameter relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is specific and unambiguous: 'Create a new category in a blog publication.' It names the verb, resource, and scope, and clearly differentiates from sibling tools like create_blog_author or list_blog_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor any prerequisites or contextual cues. It merely states the action without explaining why or when an agent should choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. 'Disconnect' implies a destructive/mutating action, but the description does not mention consequences such as token invalidation, whether the action is reversible, or required permissions. This is a significant gap for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the essential operation without redundancy. It is appropriately concise for the tool's simplicity, with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description is partially complete. It conveys the core action but lacks context such as consequences, prerequisites, or when to use it. Given the absence of annotations, the description should have disclosed more behavior to be fully complete, but the simplicity of the tool keeps this from being a major failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description mentions the account ID, but this adds no value beyond the schema's own description. It does not mention the optional brandId parameter or clarify any parameter semantics further, so it neither enhances nor harms the schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (disconnect) and the resource (social account), with the specific identifier (account ID). This uniquely distinguishes it from sibling tools like check_social_accounts or generate_connect_link, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, prerequisites, or how it differs from alternatives. It simply states the function without context, leaving the agent without enough information to choose this over other social account operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only mentions the future-time requirement. It doesn't state whether the existing schedule is overwritten, if the post must be in a scheduled state, whether the operation is reversible, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action. Every word adds value, with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with no annotations and no output schema, the description covers the core action and the key input constraint. However, it lacks behavioral context such as state prerequisites, side effects, and return value expectations, making it adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both postId and scheduledAt are fully described in the schema. The description merely repeats the future ISO 8601 UTC requirement already present in the schema, adding no new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Move a scheduled post to a new time' – a specific verb (move) and resource (scheduled post), clearly distinguishing it from sibling tools like schedule_post, cancel_post, and delete_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool vs alternatives. It doesn't mention that it's for already-scheduled posts or when to prefer it over canceling and re-scheduling. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavior on its own. It does explain the main behavior (rewriting using voice or general rules), but it omits details about side effects, permissions, return format, or any rate limits. It adds only minimal context beyond the literal action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core function and the two modes of operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (4 parameters, no output schema, no annotations), so the description provides a reasonable high-level overview. However, it lacks usage context, does not clarify the vague 'general writing rules,' and gives no sense of what the tool returns, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description mentions 'general writing rules,' which is vague and doesn't map cleanly to any parameter (voice, brandId, platform), thus failing to add meaningful semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Rewrite text') with a clear resource. It hints at two modes ('voice profile or general writing rules') which helps distinguish from a sibling like rewrite_with_voice, but it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 closely related tools like rewrite_with_voice or generate_text. There are no stated prerequisites, exclusions, or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'in the background', which implies asynchronous operation, but does not explain what that entails (e.g., job creation, polling via list_jobs, or cancellation options). Critical behavioral context such as whether this creates drafts or directly publishes is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 primary purpose. It contains no fluff or redundancy, earning full marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, 2 required) and lack of output schema or annotations, the description is too minimal. It does not explain the background process, how results are returned or tracked, or what 'schedule' entails (e.g., publishing vs. drafting). This is insufficient for an agent to fully understand the operation's behavior and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (86%), so most parameters are already described. The tool description itself adds no parameter-specific meaning beyond what the schema provides. This is an adequate baseline given the schema's richness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Generate and schedule') and the resource ('multiple posts across a date range'). This distinguishes it from single-post tools like 'generate_post' or 'schedule_post'. The 'multiple posts' and 'date range' phrasing makes the bulk scope obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for bulk scheduling but does not explicitly state when to choose this over alternatives like 'schedule_post' or 'reschedule_post'. No exclusions or alternative recommendations are given, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explains that the tool returns counts of completed, in-progress, and suggested items, which conveys a read-only nature and the output fields. However, it does not explicitly state side effects, permissions, or data freshness, and does not mention the optional brandId parameter's effect on results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the tool's purpose and output fields. Every word is informative, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one optional parameter, no output schema), the description is sufficiently complete: it specifies the output categories (completed, in-progress, suggested counts) and implies the scope (content roadmap). There is no output schema to explain return values, but the description covers the essential fields. It could mention the brandId scope, but the schema already does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes the only parameter (brandId) with a clear description ('Brand ID (defaults to active brand)'), and schema coverage is 100%. The tool description does not add any additional meaning or context about the parameter, so it adds no value beyond the schema, justifying the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool provides (progress stats with counts for completed, in-progress, and suggested items) and distinguishes it from related roadmap tools like seo_list_roadmap or seo_roadmap_get. However, it lacks an explicit verb such as 'gets' or 'returns', making it slightly less definitive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternative tools. The description does not mention any prerequisites, exclusions, or situations where another sibling (e.g., seo_list_roadmap) would be more appropriate. This leaves the agent to infer usage from the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does disclose key behaviors: requires a future datetime, validates ISO 8601 UTC format, and changes the post status to 'scheduled'. However, it doesn't discuss error handling, prerequisites (e.g., whether the post must already be in draft status), or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences, each adding value: what it does, the requirement, and the outcome. The description is well-structured and free of redundancy, though it could arguably be condensed further.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-transition tool with no output schema, the description covers the essential aspects: action, required input constraint, and resulting state. It omits only edge-case details like error behavior or prerequisite validation, which are not critical for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-documented. The description adds an example and clarifies that the datetime must be future and UTC, which is consistent with the schema's own descriptions but does not add significant new semantic information beyond reinforcing the format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Approve and schedule a draft post') and the resource ('draft post'), and specifies the resulting status change. However, it does not explicitly distinguish this tool from sibling tools like schedule_post or reschedule_post, so it is clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through the draft post context and the requirement for a future datetime, but no explicit guidance is given on when to choose this over schedule_post or other scheduling tools. The description mentions the required format but doesn't address alternative workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does state the action is permanent, which is a critical safety trait. However, it does not mention permissions, cascading effects, or whether deletion is limited to certain article statuses, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. It front-loads the core action and permanence, making it easy to scan. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete-by-ID operation, the description is minimally sufficient, especially with complete parameter documentation in the schema. However, it does not explain the return value, any restrictions on deletion, or what happens to associated data, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'brandId' and 'articleId' documented in the input schema. The description adds no parameter-specific information beyond the schema, which is acceptable given complete coverage. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'delete' and resource 'blog article', clearly distinguishing it from sibling delete tools like delete_publication or delete_asset. The word 'permanently' adds important context about the action's irreversibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as delete_publication, delete_post, or unpublishing. The description does not mention prerequisites like active brand or restrictions on article state (draft/scheduled/published).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavioral traits. It states the delete action but does not indicate whether deletion is permanent, whether it affects associated content, or if special permissions are required. The one-line description leaves significant behavioral context unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the action and resource. It is concise and contains no filler or redundant wording, fully earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough to know the tool deletes a content theme for the active brand, but lacks context on irreversibility, side effects on content that uses the theme, and any prerequisites. For a destructive operation, more contextual detail would be expected, though the tool's simplicity partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, as both brandId and themeId have descriptions. The description adds minimal context by mentioning 'active brand', which is already clarified in the brandId schema. Therefore, the description provides little value beyond the schema, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' with a clear resource 'content theme' and scope 'from the active brand'. It clearly distinguishes this from sibling tools like edit_theme or generate_themes, which handle modification and creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when deleting a content theme, but provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions or naming conflicting tools, such as edit_theme, which could modify instead of delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'edit,' without disclosing update semantics (e.g., partial vs full update), whether omitted fields are preserved, or any permission requirements. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that efficiently conveys the tool's purpose without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the high-level purpose but omits important behavioral details like partial-update behavior and return value. Given the tool's simplicity and the schema's completeness, it's minimally sufficient but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so the baseline is 3. The description mentions 'title or content instructions' but does not add extra meaning beyond the schema's field descriptions, nor does it elaborate on brandId or themeId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: editing an existing content theme's title or content instructions. This distinguishes it from theme creation or deletion tools (e.g., delete_theme, generate_themes) and specifies the mutable fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 is provided. The word 'existing' implies the theme must already be created, but there is no mention of using list_themes to find theme IDs or generate_themes to create new ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It explains the return shapes for short/medium/full detail levels and mentions filter options. However, it omits defaults (e.g., activeOnly defaults true), pagination behavior, and any side effects, and 'full = raw' is vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. The semicolon-separated detail levels are efficient, though slightly dense. Every sentence earns its place, though it could be slightly more readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and no output schema, the description covers purpose and output shapes but leaves out default values, pagination, and an explicit note that all parameters are optional. It is adequate but relies on the schema for complete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a condensed summary of the detail enum, but it conflicts with the schema (e.g., short is described as id/name/contentType vs schema's id+primary label+status; medium as tags/summary/timestamps vs schema's key summary fields+counts). No additional value is provided for other parameters, and the conflict creates confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the brand's knowledge-base items' with a specific verb and resource. It distinguishes itself from sibling tools like knowledge_get/update/delete and other list tools by naming the resource and detailing the return levels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (use when you need to list knowledge items), and it mentions filtering by tag, active status, or global scope. However, the description itself does not explicitly name alternatives or when-not-to-use; the schema's detail description does mention using get/view for a single item, but that is not in the description text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It lists updatable fields and the status enum, but does not state that itemId is required, whether this is a partial update, or what happens if the item does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the essential scope without waste. It is appropriately concise for a simple update operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers parameters, but without an output schema or annotations the description does not mention return behavior or confirm that itemId is required (though schema marks it). It is adequate but leaves some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has descriptive text (e.g., 'New status', 'Priority integer (lower = higher priority)'). The description adds no extra meaning beyond restating title, status, and priority, and omits brandId entirely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Edit') and resource ('a roadmap item'), and lists the updatable fields (title, status, priority), clearly distinguishing it from sibling tools like seo_roadmap_delete or seo_roadmap_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied ('Edit a roadmap item') but no explicit when-to-use versus alternatives (e.g., use seo_roadmap_delete to remove) is given. It provides no exclusions or alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions 'AI-driven edit' and shows it can remove line items, but it does not clarify whether the edit is destructive, reversible, or requires confirmation, nor whether it modifies the strategy in place or returns a preview. This lack of safety/effect context is a notable gap for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one core sentence plus two illustrative examples. Every element earns its place, and the front-loaded verb 'Apply' immediately conveys action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and no annotations, the description should clarify what the result of the edit is (e.g., updated strategy object, success message) and what the edit scope covers. The examples and schema partially cover scope, but the lack of return value/confirmation info leaves the description incomplete for an agent to anticipate the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with clear descriptions for all three parameters (storylineId, instruction, brandId). The description adds little beyond the schema, only contextualizing the instruction parameter via examples. Baseline 3 is appropriate since the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: applying an AI-driven edit to the current strategy using natural-language instruction. The verb 'Apply' with 'edit' and the resource 'strategy' is specific, and the examples ('Add a LinkedIn video post', 'Remove influencer outreach') make the purpose tangible. It is distinguishable from siblings like storyline_update or storyline_generate_strategy by emphasizing AI-driven, instruction-based editing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you have a natural-language instruction to modify the strategy) but does not explicitly state when to use this tool versus alternatives like storyline_add_line_item or storyline_update_line_item. The examples suggest typical edit scenarios but provide no exclusions or guidance on choosing this over more targeted line-item tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the state transition from archived to active, but does not mention whether the operation is idempotent, reversible, requires specific permissions, or what side effects occur on related data (e.g., brief, line items).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the exact purpose without any redundant or vague wording. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with two parameters and no output schema, the description states the core action clearly. However, it omits any information about return values, post-restoration state, or potential side effects, and with no annotations, the operational context is only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents storylineId and brandId. The description adds no new parameter-level details beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Restore an archived storyline back to active state.' It clearly defines the action and the state transition, distinguishing it from other storyline_* tools like create, get, update, delete, and execute.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case: when a storyline is archived and needs to be active again. However, it provides no explicit guidance on when to use this tool versus other restore tools (e.g., seo_restore_cluster, restore_lp_version) or prerequisites like confirming the storyline is indeed archived.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose that the tool returns a score and analysis, implying a non-mutating check. However, it does not elaborate on interpretation of the score, limitations, or any side effects, leaving some behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, consisting of two short sentences that deliver essential information without any fluff. Every word earns its place, and the purpose and return value are immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple detection tool, the description adequately covers what the tool does and what it returns. The absence of an output schema is partially mitigated by the mention of 'score and analysis,' though a bit more detail on the output structure could improve completeness. Overall, it is sufficient given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters ('Text to check' and 'Brand ID (uses active brand if omitted)'), achieving 100% schema description coverage. The tool description does not add further parameter-level semantics beyond the structured schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Check'), resource ('text'), and outcome ('whether text is likely AI-generated'). It also states it returns a score and analysis, making it distinct from siblings like humanize_text which performs the opposite transformation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor any exclusions or context. It is simply a standalone statement of functionality without indicating scenarios or relationships to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral transparency. It hints at an asynchronous action ('Trigger') but fails to disclose whether it blocks, returns immediately, or requires polling for completion. It also omits potential side effects like overwriting existing comparisons.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, direct and front-loaded. Every word earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must explain outcomes and next steps. It explains purpose and trigger conditions but leaves the agent guessing about how results are obtained, whether the operation is asynchronous, and what 'recompute' entails. This is a significant gap for a tool with no other context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the only parameter (brandId) with a description, so baseline is 3. The tool description adds no additional parameter semantics beyond what the schema already provides, but it doesn't need to compensate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Trigger') and a clear object ('fresh head-to-head comparison recompute'), making the tool's purpose unmistakable. It also distinguishes itself from read-only comparison tools by emphasizing the recompute action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('after adding or re-analyzing competitors') and the intended goal ('to get an up-to-date comparison'). It does not name alternative tools, but the usage context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states that deletion is permanent and irreversible, which is critical. However, it does not mention potential cascading effects on versions, assets, or permissions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core purpose. The second sentence gives the necessary confirmation step and a warning. There is no unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive operation with two well-described parameters and no output schema, the description is largely sufficient. It covers the action, the required confirmation, and the irreversibility. It could mention side effects, but that is not critical for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters (slug and confirm) with 100% description coverage. The description adds minimal value beyond the schema, only clarifying that confirm is needed to proceed, which is already encoded by const: true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Permanently delete') and a specific resource ('a landing page'). This distinguishes it from sibling tools like delete_lp_version (which deletes a version, not the whole page) and delete_side_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like delete_lp_version or unpublishing. The only instruction is to pass confirm: true, which is a procedural requirement rather than a usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavior. It mentions 'replace' (implying destructive overwrite) and the activation step, but it contradicts the schema's enabled parameter default of true. The description implies the schedule is not active after setting, yet the schema says enabled defaults to true, creating confusion about actual behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise at three sentences, front-loading the primary purpose and then providing key structural details and a follow-up action. The inline dayConfigs syntax is slightly redundant with the schema but helpful for quick understanding without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters and nested objects, the description covers the core purpose and the critical activation dependency. However, it omits the role of the enabled parameter (which defaults to true and might make the enable call unnecessary) and doesn't address potential side effects of replacing an existing schedule. The schema fills many gaps, but the behavioral ambiguity prevents a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds inline structure for dayConfigs and lists valid mediums, but this largely duplicates the schema's own descriptions. It doesn't meaningfully explain other parameters like leadTimeDays, timezone, or voiceProfile beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Create or replace the weekly content schedule for the active brand,' using a specific verb and resource. It also distinguishes itself from sibling tools by explicitly noting that activation happens via enable_weekly_schedule, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it's for creating or replacing a schedule, and it explicitly says to call enable_weekly_schedule afterward to activate it. It doesn't explicitly list when not to use it or mention alternatives like get/delete, but the activation instruction provides actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states this is a view operation and outlines the detail levels (short/medium/full) which gives some insight into the return granularity. However, it does not explicitly affirm that the operation is read-only, nor does it detail potential errors, auth requirements, or exactly what 'raw' means, leaving room for ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences with no fluff. The first sentence is front-loaded and clear. However, the second sentence's 'full=raw' is cryptic and relies on the schema for full definition, slightly reducing structural clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter view tool with 100% schema coverage, the description is fairly complete in stating purpose and detail options. Nevertheless, with no output schema, it does not explain the return structure beyond the detail levels, and it omits context like that assetId should come from list_assets (which the schema does mention). The description is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with detailed descriptions, so a baseline of 3 is appropriate. The description adds a condensed explanation of the 'detail' enum (e.g., 'short=id+type+name') but does not meaningfully expand beyond the schema's more precise definitions. It gives no additional insight into 'assetId' or 'brandId' beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'View details of a single asset by ID.' This specifies a verb (view), a resource (asset), and the scope (single by ID), which fully distinguishes it from sibling tools like 'list_assets' (list) or 'upload_asset' (create). The mention of the detail parameter further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 asset ID and need its details. However, it does not explicitly state when to choose this over alternatives (e.g., list_assets) or mention any prerequisites/exclusions. The supported detail levels offer some context but do not serve as explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of disclosing behavioral traits. It only states the action and platforms but does not mention potential side effects, reversibility, partial failure behavior, or whether it duplicates existing publications. This is a significant gap for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and free of filler. Every word adds value, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple publish tool, the description covers the main action and the prerequisite for connection IDs. However, with no output schema and no mention of return values, job tracking, or error conditions, it is only minimally viable and lacks completeness for an agent that needs to handle results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters, so the schema handles parameter semantics. The description adds a useful cross-reference for connectionIds ('Get connection IDs from list_publishing_connections'), but this is marginal beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Push' with a clear resource 'blog article' and destination 'external platforms (WordPress, Medium, Substack, etc.)'. It distinguishes itself from sibling tools like seo_publish_article and publish_landing_page by explicitly targeting external connected platforms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear usage context is provided: the tool publishes to external platforms and requires connection IDs, with a direct pointer to list_publishing_connections. However, it does not explicitly state when not to use it or mention alternatives, so it lacks full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It merely restates the bulk-reject action without detailing consequences, reversibility, permissions, or return format. For a mutation tool, this lack of side-effect information is a significant gap, warranting a low score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences with no wasted words. The action and scope are front-loaded, and the sibling reference efficiently orients the agent without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two documented parameters and no output schema, but the description omits behavioral details such as return values or state changes. While the basic purpose and parameters are covered via the schema, the absence of annotations and side-effect disclosure makes the description only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters (brandId and clusterIds) with meaningful descriptions, so the description adds minimal value beyond the schema. The phrase 'N clusters' aligns with the clusterIds array but does not provide additional syntax or format details. Given the 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool bulk-rejects clusters in a single call, using a specific verb ('reject') and resource ('clusters'). The scope ('N clusters') distinguishes it from single-reject siblings like seo_reject_cluster. The reference to the symmetric approve tool further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for batch rejection of clusters, which differentiates it from single-reject tools. It also mentions symmetry with seo_bulk_approve_clusters, providing context for when this tool is appropriate. However, it does not explicitly state when not to use it or name alternatives like seo_reject_cluster, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose a key behavior: the possibility of FREE_CAP_REACHED with a checkoutUrl. However, it does not mention other important behaviors such as article status changes, return values, or prerequisites, leaving the transparency only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with front-loaded purpose and a critical warning. Every word earns its place, and it avoids redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and a notable error, but lacks information about success return values, prerequisites (e.g., whether the article needs approval), and downstream effects. Since there is no output schema, this missing context lowers the completeness score for a publishing action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all five parameters have descriptions in the schema. The tool description adds no additional parameter-level detail beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Publish or schedule'), the specific resource ('roadmap-generated article'), and the destination ('to a publication'). It also situates the tool within a workflow ('Step 10'), distinguishing it from generic publication tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'roadmap-generated article' and 'Step 10' in a workflow, but it does not explicitly compare against sibling tools like publish_blog_article or schedule_blog_article, nor does it state when not to use it. The free-tier warning is more about error handling than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It doesn't disclose side effects, permissions, return value, or that this mutates the storyline's strategy. The field list and config tip don't cover behavioral impact, similar to the TDQS 2.9 example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, and every phrase earns its place. The config guidance is practical and concise without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 params, a nested config object, no output schema, and no annotations, the description is thin. It doesn't mention preconditions (e.g., storyline must exist), return behavior, or how to obtain storylineId, though it does provide useful context about strategy ownership.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description repeats some param names (channel, type, title, description, config) and the 'pass {}' tip mirrors the schema's config description, adding little beyond the structured data.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and resource ('new line item (deliverable) to a storyline's strategy'), clearly distinguishing it from sibling tools like storyline_update_line_item and storyline_delete_line_item. The relationship to strategy is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'new' explicitly indicates this tool is for creating line items, not updating or deleting them, providing clear context. However, it doesn't name alternative tools or explicitly state when not to use it, leaving a slight gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the basic action and does not disclose whether tags are merged, whether repeated calls are idempotent, error behavior, or any side effects. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core purpose, and no redundant content. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description covers the main action and required inputs. However, with no annotations and no output schema, it fails to mention return values, edge cases, or exact behavior when both arrays are provided or when tags are missing. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all four parameters have descriptions). The description adds 'and/or' to clarify the relationship between addTags and removeTags, but this is minimal value beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add or remove tags on an asset' with a specific verb and resource, distinguishing it from sibling tools like list_asset_tags and delete_asset. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to 'Provide addTags and/or removeTags as arrays', which indicates how to invoke the tool. However, it does not mention alternatives or provide when-not-to-use guidance relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It discloses that the tool creates a publication and returns a publicationId, but does not cover potential side effects, permissions, or error behavior. Some behavioral context is added, but it remains incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose, the parenthetical clarifies the resource, and the return value is noted upfront. No wasteful wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose and return value, and the dependency on generate_blog_post adds context. However, it omits explanations for the layout and description parameters, and does not mention potential prerequisites or failure cases. Given no output schema and no annotations, more detail would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description does not add meaning to the input parameters beyond the schema. Schema coverage is only 50% (title and brandId have descriptions, layout and description do not), and the description fails to explain the undocumented parameters, leaving gaps for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new blog publication') and clarifies the resource as the container for articles. It distinguishes the tool from siblings like generate_blog_post by noting the returned publicationId is required for that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly connects this tool to generate_blog_post by stating the publicationId is needed for that tool, giving a clear when-to-use context. It does not mention alternatives like update_publication, but the use case is well-implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals that deletion is a 'soft-delete' (non-permanent) and requires confirmation, adding context beyond the tool name. Yet it does not explain consequences, reversibility, permissions, or what happens to the asset after soft-deletion, leaving significant ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core action and confirmation requirement. Every word earns its place, with no redundancy or irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter deletion tool with no output schema, this description adequately covers the purpose and the critical confirmation requirement. It could be more complete by clarifying soft-delete semantics and expected return value, but given the tool's simplicity, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters with clear descriptions. The tool description adds no new parameter details beyond reinforcing that confirm must be true, which the schema already states as a const. Thus the description adds minimal value over the schema, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Soft-delete an asset from the brand library' with a specific verb and resource. It clearly identifies the action (soft-delete) and object (asset), distinguishing it from sibling tools like delete_theme or delete_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear that this tool is for soft-deleting an asset and instructs the caller to pass confirm:true. However, it does not mention when not to use it, alternatives such as permanent deletion or restore, or any prerequisites like brand context. The usage context is implied but not explicit about exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It communicates the destructive action ('delete') and scope (all statuses), but does not disclose irreversibility, side effects on linked resources, or permission requirements. This is a meaningful gap for a deletion tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource, then adds scope. Every word adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete operation, the description covers purpose and scope. However, it omits a warning about permanence or a distinction from cancel_post. Given the tool's simplicity, this is adequate but has clear room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (postId described as 'Post ID to delete'). The description adds no parameter-specific detail, but the schema already sufficiently documents the single parameter, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Cancel and delete') and resource ('a post'), and adds valuable scope distinction by specifying 'regardless of its current status (draft, scheduled, or posted)'. This distinguishes it from sibling tools like cancel_post, which likely only handles scheduled posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (for any post status) but does not explicitly name alternatives or provide exclusions. Since a sibling cancel_post exists, direct comparison would strengthen guidance, but the 'regardless of status' phrase offers reasonable context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It discloses that only 'active' members are listed and specifies the returned fields (role, id, name, email). However, it does not mention authentication, error behavior, or side effects, though 'List' implies a read-only operation. This is acceptable but not overly detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 14-word sentence that front-loads the action ('List') and resource, with no redundant or extraneous information. It is efficiently written and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by disclosing the return fields (role, user info with id/name/email) and the 'active' filter. It does not mention ordering or pagination, but for a simple one-parameter list tool with an optional parameter, the description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes brandId as 'Brand ID (uses active brand if omitted)' with 100% coverage. The tool description merely says 'of a brand,' which does not add meaning beyond the schema. Thus, the description adds no new parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('active members of a brand'), and the return data ('role and user info (id, name, email)'). It is specific and distinguishes from sibling tools like get_brand_info, which likely returns brand-level details rather than member listings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to retrieve a brand's active members, but it does not explicitly state when to use it versus alternatives or provide any exclusions. No direct comparison to similar tools is given, but the purpose is straightforward enough that context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the behavior for each detail level (stats only, slim item list, raw response), which goes beyond a simple 'view' statement. However, it omits any mention of authentication, rate limits, or side effects, though the read-only nature is implied by 'View'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the purpose and then efficiently enumerates the detail options. It is dense but not overly long, earning its place without redundancy. A slightly clearer separation between purpose and options would improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description does explain the return behavior for the detail parameter, which is critical. It does not mention the status filter or brandId in the description, but those are already well-documented in the input schema. The tool is a read-only view, so the absence of side-effect warnings is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description adds meaningful value by explicitly clarifying what each detail level returns ('stats only', 'slim item list (id+title+status+keyword)', 'raw response'), which goes beyond the schema's generic parameter descriptions and helps the agent select the appropriate verbosity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('View') and resource ('SEO / GEO content roadmap'), and lists key contents (blog topics, keywords, completion status). It is clear but does not explicitly distinguish itself from sibling tools like seo_list_roadmap or seo_roadmap_get, though the detail parameter behavior hints at unique capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use different detail levels, but does not explicitly state when to choose this tool over alternatives such as seo_roadmap_stats or seo_roadmap_get. The existence of sibling tools implies potential overlap, but no direct comparison or exclusion is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It states 'all unique tags' which implies deduplication, but does not mention sorting, pagination, authentication, or return format. This is minimal but sufficient for a simple read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and unambiguous. Every word contributes value, with zero redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, no nested objects), the description is complete enough. It lacks explicit return type details, but the tool's purpose is self-evident, and the active brand default is already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes brandId as 'Brand ID (defaults to active brand)' with 100% coverage, so the description adds no parameter-level detail. The description's mention of 'brand's asset library' aligns with the parameter but does not enrich it beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List') and resource ('all unique tags used across the brand's asset library'). It distinguishes itself from sibling tools like list_assets and tag_asset by focusing specifically on tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving unique tags in the asset library but does not explicitly state when to prefer this over alternatives or provide exclusions. It gives context (brand's asset library) but lacks direct guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It clearly indicates a read-only listing operation and gives context about the types of connections. However, it does not disclose any behavioral details like whether it returns empty results, requires an existing publication, or pagination. For a simple list tool, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb and resource, no filler. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low complexity (2 params, no nested objects) and the description explains what it lists. No output schema exists, but the description's examples clarify the domain. It could hint at return details, but for a simple list it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are documented in the schema with clear descriptions (publicationId as 'Blog publication ID', brandId as 'Brand ID (uses active brand if omitted)'). The description does not add additional parameter semantics beyond confirming the connection types. Schema coverage is 100%, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'list' and resource 'external publishing connections' for a blog publication, with concrete examples (WordPress, Medium, Substack). This clearly distinguishes it from sibling tools like list_publications or list_blogs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: when you need to see external publishing connections for a specific blog publication. However, it does not explicitly state when not to use it or mention alternative tools, leaving usage guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It discloses the default behavior (short list) and how to get more fields, but does not mention whether the operation is read-only, potential pagination, rate limits, or error conditions. It adds some context but lacks depth about the list's scope or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, with the primary action stated first, followed by a practical usage note. There is no unnecessary wording, making it appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description covers the core purpose and behavior. Combined with the rich schema, the agent has enough to invoke it correctly. It could mention pagination or the fact that it returns all items, but this is not essential for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers the detail parameter comprehensively, so the baseline is 3. The tool description adds minimal additional meaning ('Lists default short; pass detail=medium/full for more fields') that is largely redundant with the schema. It does not clarify any parameter details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), the resource (voice profiles), and the scope (all available), and mentions the primary output (IDs). This distinguishes it from other list_* siblings by naming the specific resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context about the detail parameter (default short, medium/full for more fields) but does not explicitly state when to use this tool vs alternatives or any exclusions. The unique resource makes usage implied, but there is no explicit guidance on when not to use it or how to choose among similar list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that only locally stored credentials are affected, implying a local scope and that server-side sessions may persist. However, it does not mention side effects such as requiring re-authentication or the impact on the current session.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that communicates the action and scope without any unnecessary words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, simple tool, this description is adequate. It states the core action and scope. However, adding a note about the consequences (e.g., 'You will need to log in again') would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to convey. The description adds no parameter information, but none is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('clear') and a specific resource ('locally stored PostKing credentials'), making it clear what the tool does. It distinguishes itself from sibling authentication tools like login_start, login_complete, and whoami, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor any prerequisites or exclusions. The usage intention is implied by the tool name and description, but not explicitly articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does state the main effect (making the page publicly accessible), but it does not mention whether the operation is reversible, any side effects, or validation requirements. There is no contradiction with annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 11 words, front-loaded with the action and resource, and contains no filler. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema, no annotations), the description sufficiently conveys the core purpose and outcome. It lacks context about prerequisites or error conditions, but for a simple publish operation it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the required 'slug' parameter with 100% coverage. The description adds no additional meaning about the parameter, such as format or how to obtain it. Baseline 3 is appropriate given the schema fully covers the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Publish' with the resource 'landing page' and states the outcome 'making it publicly accessible at its URL'. This clearly distinguishes it from sibling tools like edit_landing_page or generate_landing_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is used when a landing page should be made publicly accessible, but it does not explicitly state when to use it versus alternatives or provide exclusions. No mention of prerequisites like having an existing landing page or connected domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It accurately states the tool fetches AI-suggested assets from the brand library, but it does not disclose any potential limitations, requirements (e.g., need for existing brand assets), or whether the operation is read-only. No contradiction exists, but the transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of about 15 words. It immediately states the action ('Get') and provides the essential qualifiers ('AI-suggested', 'brand library', 'match a given post context or topic'). Every word earns its place with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (3 params, 1 required) but has no output schema and no annotations. The description explains what the tool does but does not clarify what the response looks like (e.g., returns a list of asset IDs/metadata) or any edge cases (e.g., what happens if no assets match). While adequate for basic invocation, it leaves room for ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (brandId and context have descriptions, but limit does not). The tool description does not add any additional semantics for the parameters; it merely paraphrases the context parameter ('post context or topic') and does not explain the limit parameter's behavior (e.g., number of suggestions returned). Thus, it fails to compensate for the missing limit documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('AI-suggested assets from the brand library') with a clear qualifier ('that match a given post context or topic'). It clearly distinguishes this tool from siblings like list_assets or search_stock_images by emphasizing AI-driven suggestion based on context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool should be used when a user needs asset suggestions for a given post context or topic. It does not explicitly name alternative tools or exclusions, but the context is clear from the phrasing 'AI-suggested assets' and 'brand library'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It does reveal that the tool returns an authorId, which is useful, but it does not mention side effects, uniqueness constraints, permission requirements, or error conditions typical for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the core action, and the second adds the key return value and downstream usage. Every word contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with comprehensive parameter schema coverage and no output schema, the description adequately covers the essential information: what it creates, what it returns, and how the return value integrates with sibling tools. No additional context seems necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes all four parameters (firstName, lastName, email, brandId) with individual descriptions, so coverage is 100%. The description adds no additional parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new author for blog articles' with a specific verb and resource, distinguishing it from related tools like create_blog_category and list_blog_authors. It also mentions the return value, an authorId, which clarifies its purpose in the blog creation workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an author is needed for generate_blog_post or update_blog_article by noting the authorId is used there. However, it does not explicitly state when not to use this tool or mention alternatives for listing or managing authors, leaving the guidance mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It explains the edit operation and rerender behavior, which is useful, but it does not disclose whether the edit overwrites existing content, if it is reversible, or any error conditions like out-of-range cardIndex. The mention of rerender adds value but leaves important behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no fluff. Every clause provides useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple edit but lacks a mention of the return value, error handling, or the fact that 'number' is also updatable. Given no output schema and no annotations, the description could be more comprehensive, though it covers the main edit workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds clarification for cardIndex ('1-based') and rerender ('regenerate the visual asset'), which goes beyond the schema. However, it omits the 'number' parameter even though it is editable, so it does not fully clarify all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Edit'), the resource ('a single carousel card on a post'), and the indexing convention ('1-based index'). This distinguishes it from sibling tools like list_post_cards or generate_post_carousel, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating a single card and mentions the rerender option, but it does not explicitly state when to prefer this tool over alternatives like set_post_cards or bulk editing tools. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on the transparency burden. It communicates output shape for detail='short' and 'full' and the domain concept, but breaks down for the 'medium' variant and doesn't discuss pagination, ordering, or brandId effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, no filler. The parenthetical and alternative tool reference are compact and useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter list tool with no output schema, the description plus schema are mostly sufficient. A minor gap is no mention of pagination or behavior for the 'medium' detail level, but it's acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema covers 100% of parameters, the description's detail explanation is incomplete and slightly inconsistent with the schema: it says short returns id+name, while the schema says id + primary label + status. This adds misleading rather than clarifying value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with a clear verb ('List') and resource ('blog publications'), and explains what these are in parentheses. The final sentence explicitly differentiates it from list_publishing_connections, removing ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says it is distinct from list_publishing_connections and why, telling the agent when not to use it. However, it doesn't mention other sibling list tools (e.g., list_blogs), so the guidance isn't exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on the full burden and explicitly states 'no DB writes', which is a key behavioral trait. It also characterizes the operation as informational. It does not address rate limits or auth, but for a simple read-only stats tool, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with the main verb and resource front-loaded. There is no fluff; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description leaves the return structure ambiguous ('stats' vs 'count') and does not explain the role of brandId in a 'global' dataset. Since there is no output schema, a bit more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides a full description for brandId ('Brand ID (defaults to active brand)'), so schema coverage is 100%. The tool description does not add meaning about how brandId affects the 'global' stats, so it stays at the baseline without exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return'), the resource ('global subreddit dataset'), and the specific metric ('count of known subreddits available for matching'). It distinguishes itself from sibling reddit tools by emphasizing 'global', which differentiates it from brand-specific pool tools like reddit_get_pool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via 'Informational only — no DB writes', suggesting it is safe for read-only queries. However, it does not explicitly mention alternatives or when not to use it, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does state that the tool 'immediately queues posts' and 'Returns postsCreated count', indicating a mutating action with a return value. However, it omits prerequisites (e.g., an enabled schedule), idempotency, or potential side effects, which prevents a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. It front-loads the primary action, includes a required format instruction, and ends with a relevant return-value note. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool's immediate purpose is clear, but the description lacks context about the weekly schedule system as a whole, such as whether a schedule must be configured first or what happens if no schedule exists. Given the sibling tools, a brief mention of prerequisites or expected preconditions would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reiterates the date format and mentions the date concept, but the schema already provides both parameter descriptions including the brandId default. The description does not add meaningful semantics beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Trigger' and identifies the resource ('smart-week content generation engine') with a scope ('for a specific date'). It clearly distinguishes from sibling schedule-management tools like enable_weekly_schedule and set_weekly_schedule by focusing on execution rather than configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: it triggers generation for a specific date and mentions the immediate queueing behavior. It also includes a formatting instruction ('Use YYYY-MM-DD format'). However, it does not explicitly mention alternative tools or when not to use it, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly discloses the default return behavior (bucket totals), the effect of 'detail' levels on output (medium = capped lists, full = raw API response), and the shape of the short output. It does not mention side effects or prerequisites, but the read-only nature and output details are well explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the main purpose, and then efficiently explains the behavior of the 'detail' parameter. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description does a good job explaining return values for 'short' and 'medium' detail levels. The 'full' level is only described as 'raw API response', which is somewhat vague, and no error conditions or prerequisites are mentioned. Still, the core behavior is sufficiently covered for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds valuable extra meaning by mapping 'detail' values to concrete output shapes (e.g., 'medium' yields capped keyword lists up to 50 per bucket), which goes beyond the generic enum description in the schema. It also clarifies that 'competitorDomain' is compared against the brand's coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Compare') and resource ('brand's keyword coverage against a competitor domain'), making the core purpose clear. It distinguishes from generic sibling tools by describing the bucket totals output, though it does not explicitly name an alternative such as 'seo_gap'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (whenever you need to compare keyword coverage versus a competitor) but provides no explicit guidance on when not to use it or which alternative tool to choose. The detail parameter is explained, but there is no comparison against sibling tools like 'seo_gap' or 'competitor_analyze'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the AI-driven nature, mentions optimistic concurrency via expectedVersion, and implies a mutation. However, it does not specify whether the edit is incremental or a full rewrite, whether prior content is preserved, or what happens if the brief does not exist. There is no mention of return behavior or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: a clear statement of purpose and a note about expectedVersion, with illustrative examples. It is front-loaded with the core action and avoids extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no output schema), the description covers the main action and an optional parameter but omits details about the result or expected behavior on failure. It adequately positions the tool among siblings but leaves some operational ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents all parameters. The description adds value by giving examples for the instruction and explaining expectedVersion's purpose, but this overlaps with existing schema descriptions. It does not meaningfully improve parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies an AI-driven edit to the current brief using a natural-language instruction. Specific verb ('apply'), resource ('brief'), and mechanism ('natural-language instruction') distinguish it from siblings like storyline_set_brief or storyline_update. Examples further clarify the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes a clear use case: editing an existing brief with natural-language instructions, with examples illustrating typical edits. It does not explicitly mention when not to use it or name alternative tools, but the context is unambiguous enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It adds meaningful context by mentioning the crawler runs every 3 days, implying data freshness behavior, and describes the output content (hook, template, pattern, virality reason). However, it does not explicitly state that the operation is read-only, require authentication, or mention any side effects. The cadence disclosure is useful, but the description omits broader behavioral details like pagination 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long and front-loaded with the core purpose. Each sentence contributes meaningful information: scope, output contents, crawler cadence, and supported values. It could be slightly more structured (e.g., using a list for supported niches/platforms), but it remains compact and efficient without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fairly complete for a tool with no output schema. It explains what each returned post includes, which compensates for the absence of an output schema. It covers scope (niche/platform), data freshness (crawler cadence), and supported values. It does not explicitly state authentication requirements or error handling, but given its simplicity and the presence of comprehensive schema descriptions, it provides sufficient context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides comprehensive descriptions for all five parameters, achieving 100% coverage. The description adds minimal value beyond this: it reiterates the default for 'days' and lists supported niches/platforms, which are already documented in the schema. Since the schema fully explains each parameter, the description need not duplicate that effort, but it also introduces no additional parameter-specific guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's primary function: 'Browse top-trending posts (with deconstructions) for a niche + platform.' It uses a specific verb ('browse') and identifies the resource ('top-trending posts'). It also distinguishes itself from brand-specific tools by noting it is 'Account/niche-scoped — NOT tied to a specific brand,' making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it targets niches and platforms, and it explicitly states what it is NOT ('NOT tied to a specific brand'), which serves as a when-not. It also gives practical guidance on the 'days' parameter ('use days=3 (default) for the freshest batch') based on the crawler cadence. However, it does not name alternative sibling tools, so it lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior on its own. It conveys the critical fact that adding does not activate the domain—activation requires a separate verify_domain call. However, it lacks other behavioral detail such as duplicate handling, domain ownership requirements, or side effects of setting isPrimary, which are relevant for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the primary action and immediately followed by the next-step instruction. There is no filler or repetition, making it a model of concise, structured tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 parameters, only 1 required) and complete schema coverage, the description covers the essential operational context: it adds to the active brand and requires later verification. It could explicitly state that the domain starts inactive, but this is logically implied by the verify_domain instruction. Overall, it is sufficient for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline score applies. The description's phrase 'to the active brand' echoes the brandId parameter's documented default behavior, adding no new meaning beyond what the schema already provides. The other parameters (domain, isPrimary, primaryContentType) are fully described in the schema without further elaboration needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action with a specific verb ('Add') and resource ('custom domain to the active brand'), immediately distinguishing it from sibling tools like list_domains, verify_domain, and delete_domain. The instruction to call verify_domain afterward reinforces its role as the creation step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow guidance: 'After adding, call verify_domain to check DNS and activate it.' This tells the agent when to use this tool as the first step in a multi-step process. However, it does not explicitly state when not to use it or mention alternative tools, so it stops short of full specificity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds context about default shallow listing and the ability to request more detail, but it doesn't mention output structure, potential side effects, or edge cases. This is a read-only operation, but the absence of annotations means more transparency would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and includes a relevant use case. Every word earns its place; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters and no output schema, the description is quite complete. It states the tool's scope, usage context, and how to adjust verbosity. The schema fills in parameter details. Minor gaps remain regarding the exact fields returned at each verbosity level, but these are not critical for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters with full descriptions (100% coverage). The tool description only repeats that detail can be set to medium/full, which the schema already explains thoroughly. The description adds no additional parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List all connected and disconnected social accounts for the active brand.' It uses a specific verb (list) and resource (social accounts), and the added use case 'Run before posting to confirm platform availability' further clarifies intent. This distinguishes it from sibling tools like disconnect_social_account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context for when to use the tool ('Run before posting to confirm platform availability') and how to control output verbosity ('pass detail=medium/full'). It does not mention alternatives or when not to use it, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is responsible for behavioral disclosure. It does state the return format (URLs, snippets, timestamps) and that it is for auditing, providing some transparency. However, it does not mention pagination, error behavior, or whether it is read-only, which would be valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and efficient: two sentences that front-load the purpose, then provide return details and a use case. Every sentence earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-param tool without an output schema, the description covers the key aspects: what it does, what it returns, and why you'd use it. It lacks a small amount of detail, such as potential output size limits, but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, brandId, is fully described in the schema (100% coverage), so the baseline of 3 applies. The description adds no extra parameter-specific context beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists data sources for the brand's competitive comparison, using a specific verb ('List') and resource. It distinguishes itself from sibling tools like competitor_get_comparison by focusing on raw source records, not the comparison itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: auditing comparison accuracy. However, it does not explicitly mention when not to use it or name alternatives, leaving some room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It reveals output fields including creditsCharged, lastError, and cacheSource, which hint at credit usage and caching behavior. However, it does not explicitly state whether the call is read-only, whether it charges credits, or any side effects, leaving ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, front-loading the core purpose in the first clause, then efficiently enumerating the detail levels and output fields. Every sentence and clause adds value without extraneous fluff, making it exemplary in conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description provides a good level of completeness by specifying the data returned for each verbosity option and noting the dashboard link. The main gap is the ambiguous 'full = raw', which does not sufficiently describe the full object structure, and there is no mention of pagination or error scenarios, though these are less critical for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema covers both parameters with descriptions, the tool description adds significant meaning by enumerating the exact fields returned for each detail level (short: id,domain,analysisState; medium: adds source,creditsCharged,...; full: raw). This goes beyond the schema's generic 'verbosity' explanation and helps the agent understand the semantic differences.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List') and resource ('the brand's tracked competitors'). It also distinguishes the tool by detailing output levels (short/medium/full) and a unique dashboard link. This differentiates it from sibling tools like competitor_get_overview or competitor_get_comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by showing the effect of different detail levels (short/medium/full), which guides selection based on desired verbosity. However, it does not explicitly state when to use this tool over alternatives or provide exclusions, so it falls short of a clear usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the return shape and status enum values, which is useful for a status check. However, it doesn't explicitly state read-only-ness, error behavior, or side effects, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, and packed with only essential details (status values, return shape). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status-check tool, the description is sufficiently complete: it explains the return structure and status semantics, and hints at the next step (classification). Minor gap: no mention of what happens if the brandId is invalid or probe doesn't exist, but this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the single optional brandId. The tool description doesn't add param-level detail, but the schema already handles it adequately, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Check the status of the competitor discovery probe.' It clearly distinguishes from siblings like competitor_probe (which likely starts the probe) and competitor_probe_classify (which classifies results).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case: checking probe status after initiation. It doesn't explicitly name alternatives, but its purpose is self-evident alongside sibling tools. Lacks explicit exclusions, hence not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the operation is 'permanently' destructive and requires 'confirm: true' to proceed, which informs the agent of the irreversible and guarded nature. This is significant for a delete tool, though it does not detail side effects or what happens to associated data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and scope, followed by a necessary confirmation instruction. Every word earns its place, with no redundancy or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with two parameters and no output schema, the description adequately covers the purpose, the required confirmation, and the default scope (active brand). It could mention what the response looks like or any post-conditions, but given the simplicity and lack of complex return values, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both brandId and confirm described in the input schema. The description does not add meaning beyond 'confirm: true' and 'active brand', which are already captured in the schema. Baseline of 3 applies because the schema handles parameter documentation fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'permanently remove[s] the weekly schedule for the active brand', which is a specific verb+resource+scope. It distinguishes itself from sibling tools like disable_weekly_schedule by emphasizing 'permanently', indicating a destructive operation. The mention of the confirm parameter further clarifies the required action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage instruction ('Pass confirm: true to proceed') and implies the tool is for permanent deletion of a weekly schedule. However, it does not explicitly contrast with alternatives like disable_weekly_schedule, nor does it state when-not-to-use. The usage context is implied but not fully elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It explains the main behavior—generating a secure link for OAuth—but does not mention side effects, response format, or any limitations like expiration, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences, front-loaded with the core action and then the sharing instruction. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description covers its purpose and usage. However, since both parameters are optional and there is no output schema, the description leaves some room for interpretation regarding defaults and return value, though the core is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema (brandId, platform), so the description adds no additional parameter semantics. Baseline 3 applies due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Generate a secure browser link') and the purpose ('connect a social media account, complete OAuth'). It distinguishes from sibling tools like login_start and disconnect_social_account by focusing on link generation for OAuth.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It instructs to share the URL with the user to complete OAuth, providing clear usage context. It does not explicitly mention when not to use or list alternatives, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses the core behavior (generates a PDF), the returned values (asset ID and download URL), and a prerequisite. However, it does not mention side effects (e.g., whether the generated asset is persisted, whether it consumes credits, or whether it overwrites previous versions), which is a notable gap for a generative action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, followed by the output and the key prerequisite. Every word adds value; no redundancy or irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (4 params, no output schema), the description covers the essential aspects: purpose, output format, and a critical prerequisite. It could be more complete by noting default behavior for optional parameters, but overall it provides sufficient operational context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters. The description adds context by linking postId to the post's cards, but it does little to explain style, title, or variant beyond what the schema already states. Baseline 3 is appropriate since the schema handles param documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Generate a carousel PDF'), identifies the source ('from the post's cards'), and mentions the output (asset ID and download URL). This clearly distinguishes it from sibling tools like generate_post_visual_options or regenerate_post_visual, which focus on visual options rather than a PDF artifact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear precondition ('Requires cards to be set first via set_post_cards or edit_post_card'), which tells the agent when this tool is appropriate. It does not explicitly list exclusions or alternatives, but the prerequisite provides sufficient contextual guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It does state that this is a polling operation, which implies a non-mutating read, and it enumerates the status values. But it omits details about response structure, polling frequency, or error cases, and does not explicitly confirm that the tool is safe/read-only. The minimal disclosure is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the purpose and then provides the essential usage pointer and status values. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple polling tool, the description provides the key context: how to obtain the articleId, what statuses to expect, and that it is an async-generation status. The schema covers parameter details, and no output schema is needed to convey return values. It could mention timeout/retry behavior or confirm this is a read-only operation, but the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters with 100% coverage (articleId as the ID returned by generate_blog_post, brandId as optional). The description reinforces the meaning of articleId but adds no new parameter semantics beyond what the schema provides, so it meets the baseline without exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Poll the async generation status of a blog article.' This clearly distinguishes it from sibling tools like generate_blog_post (creation) and get_blog_article (retrieval of content), while also naming the exact resource (blog article).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by instructing to use the articleId returned by generate_blog_post, implying this tool is called after generation has started. It also lists the possible statuses, helping the agent know what to expect. However, it does not explicitly mention when not to use this tool or name any alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden. It clearly states this is a read-only check, but it does not disclose whether the balance is real-time, requires authentication, or how the 'detail' parameter influences the response. The behavior is understandable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool, the description is nearly complete. It names the key returned values (balance, free-tier status), though it does not explicitly state how the 'detail' parameter shapes the response. Since the schema covers that, the overall context is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the single 'detail' parameter is fully described in the schema with enum values and behavior. The description adds no parameter information beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Check' with a clear resource: 'PostKing credit balance and free-tier status'. It fully distinguishes this tool from all siblings, none of which deal with credits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: whenever you need to check credit balance or free-tier status. Since there are no competing sibling tools for this purpose, explicit alternatives are unnecessary, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the batch limit (50), input type (public URLs), destination (brand library), and detail param effect. Missing are potential partial failure behavior, error handling, or whether the operation is atomic or synchronous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just two sentences, front-loaded with the key action and limit. Every part adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and moderate complexity, the description covers most essentials: batch size, destination, and detail param. However, without an output schema, it doesn't clarify return structure or failure reporting, which is a slight gap for a batch mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already provides detailed descriptions for all three parameters. The description adds context about public URLs and brand library but does not enhance the semantic meaning of individual parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Batch-import up to 50 assets by providing an array of public URLs' which gives a specific verb, resource, and scope. It distinguishes itself from the sibling tool import_asset_from_url by emphasizing batch import and array input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for batch import scenarios ('Batch-import up to 50 assets') and notes all are added to the brand library. However, it does not explicitly name alternatives or state when not to use this tool, such as for single imports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It usefully reveals the default detail level ('short') and the fields included ('id/slug/name/status'), and points to view_landing_page for full content. However, it does not explicitly state whether the operation is read-only, how results are paginated/ordered, or any other behavioral traits beyond the schema's already-detailed enum descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The first sentence states the primary action; the second provides default behavior and an alternative. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with only two optional parameters and fully descriptive schemas, the description covers the essential context: what it does, the default detail level, and how to get full content. It does not mention pagination or that it lists all pages, but given the simplicity and schema richness, it is largely complete. A small gap is the lack of explicit scope (e.g., 'all landing pages' vs. filtered by brand), but brandId defaults are described in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema already thoroughly explains both 'detail' and 'brandId'. The description adds a small convenience by paraphrasing what 'short' includes ('id/slug/name/status'), but this is largely redundant with the schema's own enum description. It does not introduce new meaning for either parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function as 'Lists landing pages', naming the specific resource (landing pages) and the action (list). It differentiates from the sibling tool 'view_landing_page' by directing users there for full content, making its own purpose distinct as a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage guidance: 'Default detail="short"' indicates typical invocation, and 'Use view_landing_page for full content' explicitly names an alternative for a different need. It lacks explicit exclusions (e.g., when not to use) but provides sufficient context for choosing between listing and viewing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It indicates a read-only operation ('List'), explains the active brand behavior, and describes the effects of the detail parameter. It does not mention pagination or error cases, but for a simple list tool this is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and then lists the detail options efficiently. Every word contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with two optional parameters and no output schema, the description covers the essential aspects: what is listed, the active brand scope, and return content variations. It could be more explicit about the response format or pagination, but it is sufficiently complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for both parameters. The tool description's explanation of detail levels adds a simplified overview but largely repeats what the schema already states, so it does not significantly enhance parameter understanding beyond the structured definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all content themes for the active brand with their IDs, using a specific verb and resource. It distinguishes itself from sibling tools like edit_theme, delete_theme, and generate_themes 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (for listing themes) and explains the detail parameter, but it does not explicitly mention alternatives or cases when this tool should not be used. No exclusions are provided, making the guidance adequate but not thorough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses side effects (refreshes stock photos, re-scores library assets), the default output shape ('slim option list with pickArgs'), and a conditional output field ('editInVisualEditor' when active brand is set). It omits details like persistence or permissions, but covers the core 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences with the main action front-loaded. Every clause adds value: what regeneration does, default return, parameter guidance, and a key output field. No filler or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no annotations and no output schema, the description gives a solid understanding of purpose, behavior, output defaults, and detail modes. It also flags the conditional nature of editInVisualEditor. It doesn't mention prerequisites like post existence, but the sibling tool names and general context make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all four parameters with detailed descriptions (100% coverage). The description adds nuance by explaining the default response and clarifying detail values ('short' = counts only, 'full' = raw catalog), which goes slightly beyond the schema. However, it adds nothing for platform or loadExternal beyond their existing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Regenerate') with a clear resource ('visual option set for a post') and elaborates the action ('refreshes stock photo results and re-scores library assets'). This clearly distinguishes it from siblings like generate_post_visual_options, pick_post_visual, and clear_post_visual by focusing on re-running/updating an existing set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for refreshing existing visual options but does not explicitly contrast with generate_post_visual_options or state when to choose this tool over alternatives. It does provide parameter-level guidance ('detail='short' for counts only, 'full' for raw catalog'), but lacks tool-level when/when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the post-status change ('scheduled') and the input requirement (future datetime), but omits details like prerequisites, error handling, or whether it also approves the post in addition to scheduling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences cover purpose, a comparison to a sibling, usage constraint, and outcome. No redundant information; front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple scheduling action without output schema or annotations, the description provides core functionality, the required datetime format, and the resulting status. It is largely complete, though it could mention the timezone parameter or potential failure conditions for greater robustness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already fully described. The description adds only a reformulation of scheduledAt's format and does not elaborate on the optional timezone parameter or postId beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Schedule') and identifies the resource ('a draft or approved post') with a clear outcome ('status becomes scheduled'). It also differentiates from sibling tools by referencing approve_post and implying reschedule_post is a distinct operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the tool is equivalent to approve_post, providing a comparison for when to use it. It also gives a key usage requirement ('Pass a future ISO 8601 UTC datetime'), though it doesn't discuss exclusions or when not to use it relative to reschedule_post.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the seeds are appended to existing seeds or replace them, what happens on validation failure (e.g., fewer than 3 or more than 10), or whether the operation is idempotent. The flow context is useful but does not disclose side effects or safeguards.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the step role, and every sentence earns its place. It avoids redundancy with the schema and provides only high-value flow and constraint information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple add operation with no output schema, the description provides enough context: it names the tool's position in the flow, specifies the count range, and indicates the relationship to the next tool. It does not explain potential failure modes or the exact persistence behavior, but given the low complexity, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (seeds and brandId), so baseline is 3. The description adds meaningful constraints ('3–10 seed keywords') and clarifies the semantic purpose ('describe what the brand wants to rank for'), going beyond the schema's basic type and minItems. This earns a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Add 3–10 seed keywords'), the resource (seed keywords), and its role as 'Step 1 of the SEO / GEO flow.' It also distinguishes itself from the sibling tool seo_generate_keywords by explicitly explaining that the next step expands these seeds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly identifies when this tool should be used ('Step 1 of the SEO / GEO flow') and provides a clear pointer to the next step ('After this, call seo_generate_keywords'). However, it does not mention any exclusions or alternative tools that might be chosen instead, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the key side effect ('marks it rejected and detaches its scored keywords'), which is useful. But it does not mention whether this is reversible, what happens to the keywords after detachment, or any permission requirements. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and resource, then a clear usage trigger. Every word earns its place, with no fluff or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter action tool with no output schema, the description is fairly complete. It covers purpose, usage context, and the main side effect. The absence of reversibility info and mention of restore alternatives are minor gaps, but the tool is simple enough that the description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both brandId and clusterId have meaningful descriptions in the schema. The clusterId is explicitly linked to seo_list_clusters, and brandId notes defaulting behavior. Since the schema already explains parameters, the description adds little extra semantic value, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool rejects a single cluster and explicitly names the resource ('cluster') and the action ('reject'). It also mentions a specific side effect (detaches scored keywords), distinguishing it from generic operations. The phrase 'single cluster' also separates it from the sibling bulk tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case: 'Use when a generated cluster isn't relevant.' This provides context for when to invoke the tool. However, it does not explicitly mention when not to use it or point to alternatives like seo_bulk_reject_clusters for multiple clusters, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It discloses the state change (from rejected to pending_review), but does not mention any side effects, permissions required, or behavior if the cluster is not currently rejected. This is acceptable for a simple state-change tool but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with the action and outcome. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a simple state transition and only two parameters, the description covers the essential purpose and outcome. It does not mention prerequisites (e.g., cluster must be rejected) explicitly, but that is strongly implied. There is no output schema, so behavior is sufficiently clear for the described action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well documented. The description adds no additional parameter context beyond what the schema provides. The schema descriptions for clusterId and brandId are as informative as or more informative than the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Restore') and identifies the exact resource ('a rejected cluster') and the target state ('back to pending_review'). It clearly distinguishes this tool from siblings like seo_approve_cluster or seo_reject_cluster by describing the state transition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the correct usage context: when you have a rejected cluster and want to bring it back for review. It states the outcome ('so it can be approved again'), which hints that approval is a separate step. However, it does not explicitly name alternatives or state when not to use it, such as 'use seo_approve_cluster to directly approve'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the deletion is permanent and irreversible, and explicitly requires a confirmation flag. This is key behavioral information. However, it does not mention potential cascading effects, permissions, or return behavior, but the core destructive nature is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the action and permanence, and includes the critical confirmation requirement. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with 3 parameters and no output schema, the description plus schema provide the essential context: what is deleted, how to confirm, and irreversibility. The brandId default is documented in the schema. It could mention what happens after deletion (e.g., return value), but that is not critical for a delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters, so the schema already explains itemId, brandId, and confirm. The description adds minimal extra meaning beyond confirming that confirm: true is required and the action is irreversible. This aligns with the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('delete'), the specific resource ('roadmap item'), and the permanence ('Permanently'). It distinguishes itself from sibling tools like seo_roadmap_edit, seo_roadmap_get, and seo_list_roadmap by indicating a destructive action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for deleting roadmap items when deletion is intended, but it does not provide explicit guidance on when not to use it or mention alternatives (e.g., seo_roadmap_edit for reversible changes). The instruction to pass confirm: true is more about invocation than usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the default return (full raw object) and the exact fields for 'medium' and 'short' detail levels. However, it does not mention error behavior (e.g., invalid ID), authentication requirements, or potential side effects (though likely none for a read). The detail-level shape disclosure is valuable but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. The first sentence states what it does; the second gives concise, concrete guidance on detail levels. No wasted words. All information is relevant and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with no output schema, the description adequately explains return shapes at each detail level. It covers the main functional aspects. Gaps include error cases and behavior for missing/invalid IDs, but these are minor for a low-risk read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema descriptions already explain detail levels, defaults, and itemId source. The description adds minor repetition of the same examples without introducing new meaning. It reinforces the default behavior but does not significantly compensate or expand beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'View a single roadmap item by ID.' This clearly distinguishes it from sibling tools like seo_list_roadmap (which lists items) and seo_roadmap_edit/delete (which modify/delete). The 'by ID' scope further clarifies its singular purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to get details of a single roadmap item. It also provides context on detail levels, noting lists default to 'short' and advising to call a get/view tool for medium/full detail. However, it doesn't explicitly state when NOT to use this tool (e.g., for bulk listing) or name alternatives beyond implied list behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains the iterative behavior and return types (follow-up questions or a readiness signal), but it does not disclose whether the operation is read-only or has side effects, nor does it address failure modes or rate-limit implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the main action, and contains no redundant phrases. Every sentence contributes valuable workflow context without excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description adequately explains the return behavior (follow-up questions or readiness signal) and the loop. It also connects to the next step in the process. It stops short of describing the readiness signal format or error handling, but for a simple intake tool it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters, so the baseline is 3. The tool description adds no parameter-level detail beyond what the schema already conveys, such as the default for brandId or the iterative use of userMessage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-noun pair ('Run the intake/clarification step' for 'storyline') and clearly differentiates from sibling tools by naming the next step (storyline_generate_brief). It is unambiguous about the tool's role in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call iteratively until the system has enough context and to then call storyline_generate_brief, providing clear usage context and a follow-up action. However, it does not enumerate when not to use this tool or compare with any direct alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the brief is 'locked' and the storyline is 'advancing to the strategy phase', which are meaningful side effects. However, it doesn't mention whether this is irreversible, who can do it, or what happens to any pre-existing strategy. Some context is given, but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and outcome, and ends with a clear next-step instruction. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 params and no output schema, the description covers purpose, side effects, and the next tool in the workflow. It lacks only a note on reversibility or error conditions, but overall it is sufficient for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (brandId and storylineId) adequately described. The tool description adds no extra parameter semantics, relying entirely on the schema, which is the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource: 'Confirm (lock) the brief for a storyline', and specifies the outcome 'advancing it to the strategy phase'. This distinguishes it from siblings like storyline_set_brief or storyline_edit_brief, which handle brief creation/editing rather than locking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs 'After confirmation, call storyline_generate_strategy', providing clear workflow context. It implies this is the transition point from brief to strategy, but doesn't explicitly mention when not to use it or alternatives, so it's not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool creates a new storyline and hints at a workflow, but it does not mention side effects, permissions, idempotency, or what the response contains. This is a moderate level of transparency for a create tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the action and resource, the second provides the workflow. It is front-loaded, precise, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with 3 params and no output schema, the description is mostly complete. It explains how to invoke it and what to do next. However, it does not explicitly state what is returned (e.g., storyline ID), which is necessary for subsequent calls like storyline_clarify. This minor gap prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description rephrases the prompt purpose ('describe the campaign goal') and mentions the optional title, but adds no new meaning beyond the schema. BrandId is not mentioned in the description, but the schema covers it adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') with a clear resource ('a new storyline (marketing plan) for the brand'). It distinguishes from sibling tools like storyline_update and storyline_restore by explicitly noting 'new' and by describing the creation workflow. The next-step instructions further clarify its role as the entry point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to follow with storyline_clarify then storyline_generate_brief, providing clear when-to-use context. However, it does not mention when not to use it or name alternatives (e.g., storyline_update) explicitly, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing behavioral traits. It does a good job by noting 'Permanently remove' (irreversibility) and the need for confirm: true to proceed (a non-obvious interactive step). However, it does not discuss potential side effects, permissions, or cascade behaviors beyond these core points.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states purpose, the second gives the essential instruction for proceeding. No redundant words or filler; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a destructive deletion with a confirmation mechanism, the description covers the critical aspects: what is removed (line item), from where (storyline's strategy), permanence, and the required confirm flag. It is complete enough for an agent to understand the operation, especially since no output schema exists and the resource scope is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description adds limited parameter context, mainly restating that confirm must be true (already described in schema). It does not clarify the semantics of itemId or storylineId beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('permanently remove') and resource ('a line item from a storyline's strategy'). It convincingly distinguishes itself from sibling tools like storyline_delete (which removes the entire storyline) and storyline_update_line_item (which modifies rather than deletes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its purpose and the instruction to pass confirm: true, but it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. There is no mention of when not to use it or a direct comparison to related storyline operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries the burden. It discloses async behavior, typical duration (~1–3 min), return shape ({operationId, status}), and polling instructions. It does not mention whether the existing draft is overwritten or any permission requirements, but 're-generate' implies replacement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with 'Async' and the action. Each sentence adds value: operation, return/polling, timing. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the async workflow, return contract, polling mechanism, and duration. There is no output schema and no annotations, so this description is sufficient for an agent to invoke and monitor the operation. Slight gap: no mention of prerequisites or failure behavior, but overall strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; each parameter has a clear description. The tool description adds no additional parameter semantics beyond the schema (e.g., no format details or constraints). Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Re-generate a single line item's content draft' with a specific verb and resource. The word 'Async' adds a key behavioral scope. This distinguishes it from related tools like storyline_update_line_item or storyline_execute, though alternatives aren't named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by indicating it is for regenerating a line item draft, but does not explicitly state when to use it versus alternatives such as storyline_update_line_item or storyline_execute. It provides helpful operational guidance (poll get_job, ~1–3 min), which partially compensates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It implies a partial update via 'Pass at least one field to change,' but does not explicitly state that omitted fields retain their values, nor does it mention permissions, side effects, or response format. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, tightly packed with essential information: action, target, editable fields, and invocation requirement. No filler or redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it is a simple metadata update tool without annotations or output schema, the description is mostly complete. It could explicitly say that only provided fields are updated, but 'Pass at least one field to change' conveys that idea. The rich schema fills in the remaining parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 7 parameters (100% coverage). The description itself only enumerates some fields and adds no extra syntax or format details beyond what the schema already documents. Baseline 3 is appropriate when schema handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (Update), the resource (storyline), and the specific metadata fields (title, live status, dates). This distinguishes it from sibling tools like storyline_create, storyline_get, and storyline_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage requirement: 'Pass at least one field to change.' This guides the agent on when the tool is appropriate and what input is needed. It does not explicitly list exclusion cases or alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that this is a partial update ('Pass only the fields to change'), which is a key behavioral trait. However, it does not mention potential side effects, required permissions, return format, or error scenarios, leaving some ambiguity for a mutation tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that quickly states the action, resource, and key usage instruction. Every word is informative, and there is no redundancy or clutter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward update tool with 8 parameters fully documented in the schema, the description covers the core functionality and the crucial partial-update behavior. It lacks an explicit return-value description, but the absence of an output schema makes that less critical. The sibling context reinforces its role, making it sufficiently complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal semantic value by mapping 'select/deselect' to the selected param and listing config, title, description, targetDate, but it does not explain the brandId param or the structure of config beyond what the schema already provides. It does clarify that only provided fields are changed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('line item on a storyline') and lists the exact fields (select/deselect, retitle, change description, targetDate, config). This clearly distinguishes it from sibling tools like storyline_add_line_item, storyline_delete_line_item, and storyline_regenerate_line_item, which handle different operations on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by listing the editable fields and instructing 'Pass only the fields to change,' implying partial update semantics. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough given the sibling names and the resource-specific action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the key behavioral trait of a partial update ('Only the fields you pass are changed'). However, it does not mention side effects, authentication requirements, error behavior, or return format, which would be valuable for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The first sentence front-loads the purpose and main fields. The second sentence efficiently handles partial-update semantics and sourcing the required ID.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, no output schema, no annotations), the description covers the essential aspects: partial update, ID source, and distinction from create. It could mention response behavior or permissions, but the provided context is sufficient for basic correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, with descriptions for brandId, domainId, description, and publicationId. The description adds meaning by grouping 'domain/routing config' (likely covering domainId, pathPrefix, routingType) and clarifying that publicationId comes from list_publications or list_blogs. It also explains partial update semantics. However, brandId is not mentioned in the description and some fields lack specific guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Update an existing blog publication's metadata' and enumerates specific fields (title, description, domain/routing config, layout). It explicitly distinguishes from create_publication, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: use this to update an existing publication, not create one. It also tells the user where to obtain publicationId (list_publications or list_blogs). It does not explicitly exclude other sibling tools like update_blog_article, but the phrase 'blog publication' vs 'blog article' sufficiently differentiates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly discloses the destructive side effect of discarding buffered chunks, which is key behavioral information. However, it does not cover potential edge cases like invalid uploadId or idempotency, but for a simple cancel operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the core action. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description adequately explains the purpose and side effects. It could mention the upload workflow context or what happens after abort, but it is complete enough for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with a clear description for uploadId ('Upload ID returned by upload_asset_begin'). The tool description does not add any parameter-specific meaning, so the schema already provides the necessary semantics, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool cancels an in-progress chunked asset upload and discards buffered chunks. It uses a specific verb and resource, and distinguishes itself from sibling tools like upload_asset_finish or upload_asset_chunk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'in progress' implies the tool is appropriate during an ongoing upload, but there is no explicit guidance on when to use this tool versus alternatives (e.g., upload_asset_finish) or when not to use it. The context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that chunks are ordered and contiguous, which is important behavioral context. However, it doesn't mention error handling, idempotency, or consequences of violating the order requirement. It also doesn't state that a follow-up call to upload_asset_finish is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences, front-loaded with the action verb, and no redundant wording. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool in a multi-step flow, the description covers the essential usage context (prerequisite, ordering) and references the companion tool. It lacks detail on error responses or completion step, but these are arguably handled by sibling tools and the schema is sufficient for parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents uploadId, index, and fileBase64Chunk with clear descriptions. The tool description reinforces the ordering constraint but doesn't add significant new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Send one chunk'), the object ('base64-encoded file'), and the prerequisite ('previously started with upload_asset_begin'). It distinguishes itself from sibling tools by describing its specific role in the chunked upload sequence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use this tool (after upload_asset_begin) and adds explicit ordering requirements ('in order, index starting at 0, with no gaps'). It doesn't explicitly list alternatives or when not to use it, but the context makes it clear this is for chunked uploads only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior, and it does cover the main actions and return value. However, it omits important behavioral traits such as irreversibility, failure behavior when chunks are missing or integrity check fails, and whether the operation can be called multiple times. The description adds value beyond the name but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the purpose, and every phrase earns its place. It describes what it does, how, and what is returned without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description covers the core aspects: purpose, process, and return value. It lacks explicit error/prerequisite details, but for a finalize step in a well-known flow it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description already covers the single parameter ('Upload ID returned by upload_asset_begin'), giving 100% coverage. The tool description does not add further meaning about the parameter's format, constraints, or usage, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Finalize' and identifies the precise resource ('chunked asset upload'). It explains the process (reassembles chunks, verifies integrity, uploads to brand library) and return value (asset ID and URL), clearly distinguishing it from sibling tools like upload_asset_begin, upload_asset_chunk, and upload_asset_abort.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this is the final step in a chunked upload flow, referencing 'buffered chunks' and the upload ID from upload_asset_begin. However, it does not explicitly state prerequisites or conditions like 'after all chunks are uploaded' or exclusions (e.g., 'not for non-chunked uploads'), leaving some room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the previewUrl behavior and detail-level contents, but does not explicitly state read-only status or potential side effects. The name 'view' suggests a safe read operation, but that's inferred rather than stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, then compactly conveys the detail level behaviors. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description covers key return fields per detail level and mentions the preview URL form. It could be more structured but is sufficient for a simple view operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already documents both parameters with 100% coverage. The description enriches the 'detail' parameter with tool-specific meanings (what each level returns), adding value beyond the schema's generic verbosity explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States exactly what it does: 'View the unpublished draft of a landing page.' Specific verb+resource+scope, clearly distinguishing from sibling tools like view_landing_page or view_lp_version that target published or versioned content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context (draft vs published) but does not explicitly name alternatives or exclusion criteria. The name and description imply use for drafts, but an agent might need to infer the difference from sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the action (tagging) but does not explain potential side effects (e.g., overwriting existing tags, reversibility, permissions, or error behavior). For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core action, and every sentence adds value. The example is compact and directly demonstrates usage without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple tool with no output schema, the description provides essential context: its position in the workflow, the input format with an example, and the next step. This is sufficient for an agent to select and invoke it correctly, given the sibling tools and schema information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explicitly listing the intent enum values and providing a JSON example that clarifies how the 'updates' array should be structured. This helps the agent invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Tag keywords by search intent and/or user tags.' It also positions it as 'Step 3 of the SEO / GEO flow,' which distinguishes it from sibling tools and clarifies its role in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Step 3 of the SEO / GEO flow' and explicitly mentions the next step ('After this, call seo_generate_clusters'). This provides clear context on when to use the tool, though it doesn't list exclusions or alternative tools. The example also clarifies the expected input format.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It does state the primary side effect (changing session default), but lacks details on persistence, scope, or whether it overrides an existing active brand. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action. Every word earns its place; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description fully explains what the tool does and the resulting state change. It is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes brandId as 'The brand ID to activate'. The description adds little beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and resource ('active brand') and clearly identifies the session-scoped nature. It distinguishes from siblings like create_brand or list_brands by focusing on activating an existing brand for subsequent operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence, 'All subsequent tools will use this brand by default,' explicitly conveys when to use this tool (before other brand-dependent operations). It does not provide explicit exclusions or alternatives, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description correctly shoulders the burden of disclosing behavioral traits. It explicitly states 'Permanently' and 'irreversible', which are critical for a delete operation, and scopes the action to 'from the brand'. However, it does not mention permissions or return values, which are less critical given the straightforward nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and a key warning. There is no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with complete schema coverage and no output schema, the description is complete. It covers the essential context (irreversibility, scope) and does not need to explain return values or additional details, as the schema handles parameter documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional context beyond what the schema already provides for templateId and brandId; the irreversible warning is behavioral, not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Permanently delete' and identifies the resource as 'content template from the brand', clearly distinguishing it from sibling tools like template_update, template_extract, and template_pick. It precisely states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool or name alternatives, but the warning 'irreversible' implies use only when deletion is intended. No exclusion criteria or alternative tool references are provided, so guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does reveal the return fields (name, price, monthly credits, billing interval options), which is useful. However, it does not explicitly state that the operation is read-only, whether authentication is required, or that there are no side effects. For a simple parameter-less listing, this is adequate but leaves some implicit assumptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the primary action and key details front-loaded in the first sentence. The second sentence adds a useful pointer to the related billing_subscribe tool without redundancy. Every sentence earns its place and there is no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (zero parameters, no output schema), the description is reasonably complete. It covers what the tool returns and its role in the billing workflow via the billing_subscribe reference. Minor omissions around error conditions and authentication are present, but they are not critical for this straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty, so there are zero parameters to document. Per the baseline rule for 0-param tools, the description adds value by detailing the output fields, which complements the schema information and gives the user a clear idea of what to expect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to list available PostKing subscription tiers. It specifies a concrete verb ('List') and resource ('available PostKing subscription tiers'), and even enumerates the returned data (name, USD price, monthly credits, billing interval options). This distinguishes it from siblings like billing_subscribe, which creates a subscription, and billing_list_packs, which lists packs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly points to billing_subscribe as the next step for creating a subscription Checkout session, providing an alternative tool for a related action. However, it does not explicitly contrast this tool with billing_list_packs or state when not to use this tool, so it gives only partially clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose the non-destructive state change. However, it omits any details about permissions, idempotency, or response behavior, keeping it moderately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver the action, scope, outcome, and alternative in a front-loaded manner with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one documented parameter and no output schema. The description adequately covers what, when, and why, though a note on return value or side effects would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter postId is fully documented in the schema, so the description adds no extra meaning. Baseline 3 is appropriate since the schema does all the heavy lifting and no additional semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'cancel' targeting 'scheduled or approved post' and explains the outcome ('reverting it to draft status'), clearly distinguishing it from sibling delete_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use (scheduled or approved posts) and provides an alternative: 'Use delete_post to remove it entirely.' This gives clear context and an exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It discloses that the delete is soft (reversible), that credits are not refunded, and explicitly how to restore. This gives key behavioral context beyond a simple 'delete' statement, though it doesn't address what happens to associated data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each serving a purpose: action, caution, and restore instructions. No fluff or redundancy. Fully front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with 2 parameters and no output schema, the description covers key context: soft-delete behavior, refund policy, and restore path. It doesn't explain what happens to related data (e.g., analyses), but that's a minor gap for this scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have clear descriptions. The tool description adds no additional parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Soft-delete a tracked competitor from the brand.' The verb 'soft-delete' is specific and distinguishes this from hard delete, and the mention of restoration via competitor_update provides clear differentiation from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names competitor_update as the restore path, giving a clear alternative. It also warns that 'No credits are refunded,' which is relevant usage context. It doesn't list exclusions or when not to use, but the guidance is sufficient for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It transparently discloses the null return behavior and the specifics of short/medium detail levels (fields included), which adds valuable context beyond the schema. However, it doesn't describe error conditions or the full content of 'raw', leaving a small gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the primary purpose, and every clause earns its place. It efficiently conveys the resource, the detail levels, and the null-case fallback without any fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description compensates reasonably by explaining the null return and the detail level output differences. It does not fully describe the 'full' raw structure, but the schema's detail parameter already hints at 'complete object'. For a relatively simple get tool, this is adequately complete for an agent to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with detailed descriptions for both parameters, including the detail enum semantics and brandId default. The description adds minor extra meaning by specifying the exact fields for short ('id,status,generatedAt') and medium ('summary excerpt'), but this largely overlaps with schema content. Baseline of 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource 'competitive landscape overview', and immediately distinguishes itself from the sibling tool 'competitor_generate_overview' by mentioning it for the null case. This clearly identifies the tool's function and differentiates it from related competitor tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit when-not situation: 'Returns null when no overview exists — use competitor_generate_overview to create one.' This gives clear guidance for a common edge case, though it doesn't elaborate on when to use this over other competitor tools like competitor_get_comparison. The context is sufficient for most use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the side effects of each classification value, which is essential for a mutation tool. It also clarifies what is modified ('probe JSON only' for non-direct) and states the return value. This gives the agent transparency into the operation's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences that pack in the action, side effects, usage constraints, and return value without any filler. It is front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but the description explicitly states the return shape ('Returns { candidates } — the updated full candidate list'). It also provides the state prerequisite and per-domain call limit. For a 4-parameter tool without annotations, this is a complete and self-contained description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds important context for the classification values by explaining that 'similar' and 'not_relevant' update the probe JSON only, which is implied but not explicitly stated in the schema. This adds value beyond the schema, but not significantly for other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Classify a discovered (or manually added) competitor candidate.' It differentiates from sibling tools like competitor_probe and competitor_add by specifying the three-way classification and its distinct side effects ('direct' seeds a BrandCompetitor row; 'similar' and 'not_relevant' update the probe JSON only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage prerequisites: 'Call once per domain' and 'Probe must be in completed state first.' It doesn't name alternative tools but implies this is the classification step after competitor discovery, which is clear given sibling names like competitor_probe and competitor_probe_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that excludeFromSeoPull removes from keyword-gap pull without deleting, and empty body restores soft-deleted. However, it omits permissions, effect on other fields, and response format, so some gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, no filler. Every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the primary update action and the special restore scenario. No output schema, but for a simple update tool the description gives sufficient context to use it correctly alongside the other competitor tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, but the description adds functional meaning: it explains 'excludeFromSeoPull' as removing from keyword-gap pull without deletion and clarifies the empty-body restore behavior. This goes beyond the schema's basic property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Update a competitor's settings', a clear verb+resource statement. It then specifies the exact behavior for 'excludeFromSeoPull' and the restore case, distinguishing this tool from sibling tools like competitor_add or competitor_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: toggling excludeFromSeoPull for exclusion without deletion, and sending an empty body to restore a soft-deleted competitor. It doesn't explicitly name alternatives or exclusions, but the usage scenario is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It reveals a significant side effect: subdomain mode creates a separate Domain row requiring its own DNS verification. This goes beyond the basic operation and warns about a non-obvious behavior, though it does not mention potential errors (e.g., root mode 409) which are only in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and then efficiently covers the three routing modes. Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, enum, side-effect for subdomain), the description covers the most critical nuance (separate Domain row verification) but does not explicitly state what the function returns or all preconditions (e.g., domain must belong to the same brand). However, the rich schema descriptions fill most gaps, making this sufficiently complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minor context by showing example URLs for path and subdomain modes, but it does not introduce new parameter semantics beyond what the schema already provides (e.g., routingType enum details). The value added is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (connect) and clearly identifies the resource (verified domain) and target (blog publication), with an explicit outcome ('articles are served from that domain'). It also enumerates the three routing modes, distinguishing this from sibling actions like add_domain or verify_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies prerequisites by stating 'verified domain' and 'blog publication', and it provides mode-specific guidance (e.g., subdomain requires separate DNS verification). It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to know when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait: the deletion does not destroy connected blogs/landing pages, only unlinks them. This is valuable safety information. However, it does not mention any prerequisites, failure conditions, or return behavior, which would enrich transparency further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two short sentences to convey both the action and the critical side effect. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete-by-ID tool with one parameter and no output schema, the description covers the essential context: what is deleted and what is preserved. It lacks information about potential restrictions or failure modes, but given the tool's simplicity, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter domainId, already specifying that it is the ID from list_domains. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Remove' and the resource 'custom domain', clearly distinguishing it from sibling tools like delete_publication or delete_landing_page. It also clarifies the scope by stating that connected blogs and landing pages are unlinked but not deleted, which further differentiates it from content deletion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (to remove a custom domain) and provides important context about the consequence: connected content is unlinked but not deleted. It does not explicitly name alternatives or exclusions, but the non-destructive effect guides proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing destructive effects. It states 'Permanently delete' and warns about server-side rejections. It also clarifies the need for confirm: true. This covers the key behavioral traits, though it could additionally state the impact on restore_lp_version or audit history, but that is not essential for use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with clear front-loading of the primary purpose. It wastes no words, immediately conveys the destructive nature, and then lists critical constraints. Highly efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter destructive tool with full schema coverage and no output schema, the description provides sufficient context: what it does, permanence, rejection conditions, and confirmation requirement. It doesn't explain return values or what happens to related versions, but that's not strictly needed. It's complete enough for an agent to decide when to call safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all three parameters, so the baseline is 3. The description adds minimal extra meaning beyond the schema—'historical' hints at the versionId's role, and 'Pass confirm: true' reinforces the required boolean, but the schema already states these. No significant new semantic detail is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Permanently delete'), the resource ('historical landing page version'), and distinguishes it from deleting the whole page (delete_landing_page) or side page versions. 'Historical' also differentiates it from the published version, making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when the operation will be rejected (published version or only remaining version), providing clear usage boundaries. It does not explicitly name alternative tools, but the context implies you'd use list_lp_versions to get the versionId and delete_landing_page for whole-page deletion. The constraints effectively guide the agent on valid versus invalid use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It adds value by stating 'without changing its configuration' and requiring prior creation, but it does not mention idempotency, error behavior, permissions, or side effects. This leaves gaps, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every clause adds essential context (prerequisite and non-configuration). No wasteful language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-change tool with one optional parameter, the description covers the purpose, prerequisite, and key constraint. It could be more explicit about what enabling does functionally, but the sibling set and simple schema make the description reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, and brandId is clearly described ('defaults to active brand'). The tool description adds no additional parameter meaning, so the baseline of 3 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function ('Enable the weekly content schedule') and specifies that it does not change configuration, distinguishing it from set_weekly_schedule. The verb 'Enable' plus the resource 'weekly content schedule' makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit prerequisite ('must already be created with set_weekly_schedule') and an implicit when-not (do not use if you want to change config; use set_weekly_schedule instead). This effectively guides the agent on when to use this tool versus the primary sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the default return fields (id+status+scheduledAt), the effect of detail levels, and the 'sorted by date' behavior. This is good transparency for a read-only view tool, though it doesn't mention potential edge cases like empty lists, timezone handling, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. It leads with the primary purpose, then states return behavior, then gives the alternative. This is an optimally concise structure for a simple getter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return values—and it does, by specifying default fields and detail-level verbosity. It also covers the main differentiation from get_post. However, it doesn't explicitly mention that the 'days' parameter controls the horizon, though that is in the schema. Given the simplicity and solid schema coverage, this is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes all 3 parameters (days, detail, brandId) with detailed descriptions, so coverage is 100%. The tool description itself only reinforces the 'detail' parameter behavior, adding minimal value beyond the schema. Since the schema is comprehensive, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('View') with a clear resource ('upcoming scheduled posts') and a distinguishing feature ('sorted by date'). It explicitly differentiates from get_post ('For a single post use get_post'), so the agent knows exactly what scope this tool covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit alternative: 'For a single post use get_post.' It implies that this tool is for viewing lists of scheduled posts, which is clear context. However, it doesn't explicitly state when not to use this tool versus other list-oriented siblings (e.g., list_posts), though the 'scheduled' and 'sorted by date' framing offers decent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It does reveal key outcomes (creates drafts, returns id+title+slug by default, detail='medium' for wordCount), but it doesn't cover potential failure modes, duplicate handling, required permissions, or whether imports are reversible. This is more than a bare 'import' but still leaves significant unknowns for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the core purpose front-loaded. The second sentence adds precise output behavior and a sibling-tool pointer. No redundancy with schema fields; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 5 parameters (2 required), the description covers the essential success path: what the tool does, what it returns by default, and how to get more detail. It omits failure behavior and the limit parameter, but the schema documents limit well, and the pointer to get_blog_article helps agents inspect results. Reasonably complete for an import/draft tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so baseline is 3. The description adds value by pinning down the meaning of detail: 'use detail="medium" for wordCount' and clarifying the default short output as id+title+slug. However, it does not explain limit or brandId semantics beyond what the schema already states, and the 'title+slug' vs schema's 'primary label+status' could be slightly ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Import articles from an external blog, RSS feed, or Blogger URL into a PostKing publication as drafts.' This clearly distinguishes it from sibling tools like get_blog_article or import_asset_from_url, and the destination/draft state is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete guidance on when to use the tool (for external blogs/RSS/Blogger imports) and explicitly directs users to get_blog_article for inspecting individual articles. It also hints at detail-level usage, though it doesn't discuss when an alternative import method (e.g., import_assets_csv) might be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a critical security behavior: 'Does NOT show raw tokens.' It also explains the default behavior and the effect of the detail parameter. It does not mention pagination, rate limits, or permissions, but for a simple list tool, the key behavioral aspects are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding value: purpose, key output fields/security note, and parameter guidance. It is front-loaded with the main function and contains no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, this description is nearly complete. It covers the purpose, the fields returned, the security caveat about raw tokens, and the detail parameter behavior. The only minor gap is that it does not state whether results are paginated or limited, but this is not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a thorough description of the 'detail' parameter, including enum values, defaults, and examples, so schema coverage is 100%. The description merely restates the default ('Lists default short') and the effect of medium/full, adding no new information beyond the schema. Hence, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List all API keys on the account.' It specifies a precise verb ('List'), a resource ('API keys'), and scope ('all on the account'), which distinguishes it from sibling tools like create_api_key and revoke_api_key. It also mentions the fields shown (prefix, scope, revocation status), adding clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on how to adjust verbosity: 'Lists default short; pass detail=medium/full for more fields.' It implies that this tool is for listing/auditing keys, while create/revoke are for other operations. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the default return shape (id+name), the effect of the detail parameter (medium for email/social links), and the active-brand scoping. It omits pagination/error behavior, but for a simple read-only list tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the core purpose and scope, the second clarifies output verbosity and gives a practical integration tip. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter list tool with no output schema, the description covers purpose, default output, detail levels, and integration. It does not specify sorting, pagination, or whether archived authors are included, but the description is sufficiently complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% parameter coverage, including detailed explanations of the detail enum and brandId fallback. The description adds only a specific example of what medium returns (email/social links), which is a minor increment beyond the schema's generic 'key summary fields + counts'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List all blog authors for the active brand.' This clearly distinguishes it from sibling tools like list_blog_categories and create_blog_author. The active-brand scope and default output are also stated upfront.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys when to use this tool (enumerate authors for the active brand) and adds a downstream integration hint by noting author IDs can be passed to generate_blog_post or update_blog_article. It does not explicitly exclude alternative list tools, but the purpose is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It mentions the effect of the detail parameter (more fields including SSL status, verification, connected blogs/landing pages) but does not explicitly state read-only nature, potential pagination, or behavior for empty results. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just two sentences: the first states the primary purpose, the second explains the detail parameter. It is front-loaded and every word contributes to understanding. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (two optional parameters, no output schema), the description is quite complete. It covers the main behavior and the key optional parameter's impact. However, it does not mention response shape or potential limits, but for a list tool with this level of complexity, the provided information is nearly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters fully (100% coverage), so the baseline is 3. The description adds extra value by listing specific fields available at higher detail levels ('SSL status, verification, and connected blogs or landing pages'), which is information not in the schema's parameter descriptions. This elevates the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List all custom domains for the active brand.' It clearly identifies what the tool does and scopes it to the active brand, distinguishing it from other list tools like list_brands or list_assets. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that the default is 'short' and instructs to pass 'detail=medium/full' for more fields, which is clear usage guidance for selecting the right detail level. However, it does not explicitly contrast with alternative tools (e.g., a hypothetical get_domain), though none exists among siblings. The context is sufficient for a list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses the default return fields (id+status+scheduledAt) and detail levels, which is useful. However, it does not mention pagination, sorting order for 'recent', or any permission requirements, leaving gaps in behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and every sentence adds value. No fluff or redundant repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 5 optional parameters and no output schema, the description covers the main return shape, filters, and usage guidance. It lacks explicit details on pagination and sorting, but the schema covers limit constraints. Overall, it is quite complete for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 40%, so the description must compensate. It explains status usage and detail levels, but does not mention limit or brandId beyond what the schema already states. The description adds some meaning but not complete coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('recent posts and drafts'), and explicitly distinguishes from get_post for single posts. It clearly states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'Use status='created' to find unscheduled drafts' and 'For a single post use get_post.' This clearly differentiates from an alternative and gives a concrete use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses that default detail is 'short', and that the response always includes top-level currentVersionId and publishedVersionId, which is valuable behavioral context. It lacks details like pagination or item structure, but for a list operation this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each providing distinct value: core action, default behavior, and pointer to sibling tool. No redundant text or filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the essential purpose, default behavior, key response fields (draft/live IDs), and directs to the view tool for content. It doesn't describe the list item structure or ordering, but for a straightforward list with detail levels, this is adequate though not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reiterates the default detail and mentions the top-level response fields, but doesn't add any parameter-specific meaning beyond what the schema already provides. The enum values and descriptions are fully captured in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'List' with resource 'all saved versions of a side page' immediately clarifies the function. The description also distinguishes from siblings by noting the top-level draft/live IDs and by pointing to view_side_page_version for section content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that currentVersionId (draft) and publishedVersionId (live) are always included 'so an agent can tell draft vs. live without a second call', which gives clear context for when to use this tool. It also explicitly recommends view_side_page_version for viewing section content, effectively indicating an alternative for deeper inspection. However, it doesn't contrast with list_lp_versions or other sibling tools, though the difference is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the async behavior (returns operationId to poll with get_job) but does not mention potential overwriting of existing content or other side effects. It provides some behavioral context beyond schema, but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with four concise clauses, front-loading the core action and then providing the key usage guidance. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async AI regeneration tool, the description explains the operationId polling mechanism and the alternative for targeted edits. It omits details about what happens to existing content, but the schema covers required parameters, making this largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a small bit by mentioning section restriction, but does not elaborate on instructions or voiceProfileId beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function—regenerating a landing page's content using AI—with specificity about optionally restricting to sections. It distinguishes itself from the sibling tool vibe_edit_landing_page, making its unique purpose obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'For targeted edits to an existing page, prefer vibe_edit_landing_page,' giving clear when-not and alternative guidance. It also instructs to 'poll with get_job' after receiving an operationId, showing how to track progress.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully explains that PostKing handles all URL crawling internally and clarifies detail levels. However, it does not state whether generated content is saved to the library, whether credits are consumed, or whether any side effects occur, leaving some behavioral ambiguity for a creation-oriented tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the core purpose in the first sentence, follows with a high-priority caveat, and then lists supported types and the detail parameter. Every sentence contributes actionable information without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 15 parameters and no output schema, the description covers the essential decision points: source and target types, URL handling, and output verbosity via detail. It relies on the schema for individual parameter details (which is acceptable given 93% coverage), but the lack of an output schema means the overall return structure is only partially explained through the detail-level descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already describes most parameters (93% coverage), the description adds crucial semantic value by emphasizing that sourceUrl must be passed directly and that the agent should not fetch or crawl the URL itself. It also summarizes source/target enums in a scannable way, reinforcing the parameter relationships beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase ('Turn a URL, text, blog post, or existing PostKing post into new content') that clearly identifies the tool's resource and function. It also enumerates valid source and target types, distinguishing this repurposing capability from generic content generation tools like generate_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational guidance, most notably the instruction to pass URLs directly via sourceUrl and not to crawl them first, which prevents redundant agent behavior. It implies when to use the tool (when repurposing existing content) but does not explicitly contrast it with sibling tools or state when not to use it, leaving room for clearer alternative selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait beyond the schema: 'This does not touch the published version', which clarifies that the operation is limited to the draft. Since no annotations are provided, the description carries the burden, and it does so by clarifying the draft-only scope, though it does not mention reversibility or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise, front-loaded sentences that immediately state the action, then provide a pointer to the companion tool list_lp_versions, and finally clarify the scope with 'This does not touch the published version'. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema and no annotations, the description covers the core action, prerequisite for obtaining a valid ID, and the key scope limitation. While it omits details like error conditions or reversibility, it provides enough context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters fully (slug as 'Landing page slug' and versionId as 'Numeric version ID from list_lp_versions to restore as the draft'). The description reinforces the versionId sourcing via list_lp_versions but adds no new semantic information beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase 'Undo/rollback the draft to a prior version' that clearly identifies the action and resource. It distinguishes itself from siblings by explicitly stating it does not touch the published version, which is a unique scope not implied by the tool name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool by instructing to 'Find valid version IDs via list_lp_versions', which also points to a prerequisite sibling tool. However, it does not explicitly mention situational alternatives or exclusions, though the scope is straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility and clearly discloses the soft-delete behavior: rows stay in the DB but are filtered out of all queries. It also highlights the confirmation requirement ('Pass confirm: true'). Minor gaps remain around reversibility and response format, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with purpose, then behavior, then usage. Every sentence adds value with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (bulk delete, confirmation flag, soft-delete behavior) and lack of annotations/output schema, the description covers the essential aspects well. It does not explain return values or edge cases like idempotency, but these are not critical for a bulk delete operation with clear usage guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds slight context by mentioning 'keywordIds' are derived from seo_list_keywords, but does not significantly enrich the parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Soft-delete N SeoScoredKeyword rows in one call' with specific behavior (sets deletedAt). It distinguishes this bulk operation from singular delete tools by emphasizing 'in one call' and 'Housekeeping op'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Housekeeping op — not part of the main flow' and a concrete example ('after filtering seo_list_keywords by relevanceMax'). However, it does not directly compare to the singular delete tool (seo_delete_keyword), leaving some ambiguity about when to prefer one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must explain behavior. It does state the core transformation and input selection behavior. However, it does not disclose side effects such as whether an existing roadmap is overwritten, whether clusters must be approved, or any prerequisites beyond the input IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. It front-loads the action, explains parameters in the second sentence, and provides next-step guidance in the third. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, no output schema, and no annotations, the description covers the essential invocation details and workflow position. It does not describe the returned roadmap structure, but sibling tools like seo_list_roadmap and seo_roadmap_get cover retrieval, making this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema already describes each parameter at 100% coverage, the description adds critical semantics: the either/or relationship between clusterId and clusterIds, and the 'omit both to roadmap all clusters' default. This goes beyond the schema's simple per-field descriptions and clarifies invocation choices.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Turn') and clearly defines the resource and outcome: 'clusters' into a 'prioritized content roadmap of blog articles'. It distinguishes itself from sibling roadmap tools by emphasizing generation rather than listing or editing existing roadmaps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly places the tool as 'Step 6' in a workflow, tells the caller exactly which parameters to pass (clusterId or clusterIds, or omit both), and names the next step (seo_write_article). This gives clear context for when to use it, though it does not explicitly mention when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that both draft and published items are included, and it notes this mirrors the dashboard Results tab, adding context about the tool's provenance and scope. It does not cover all behavioral traits (e.g., sorting, performance), but for a list operation, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action and resource, then adds scope and a usage preference. Every sentence contributes value: what it lists, statuses included, and a recommendation. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is quite complete for a list tool with no output schema: it states what is included, the filter mechanism, and the canonical status. It does not explain how it relates to sibling list tools like seo_list_briefs or list_side_pages in detail, but the 'prefer it over' guidance partially covers this. Given the schema richness, the description suffices for safe use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% as all six parameters have descriptions, so the baseline is 3. The description's only parameter-related note is 'Use kind to filter,' which adds no new meaning beyond the schema. It does not enrich the understanding of limit, cursor, detail, or status beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('Generated Results'), scope (blog articles + side pages + comparisons), and distinguishes it from alternatives by declaring it the 'canonical' list and explicitly telling users to prefer it over reconstructing results from briefs. The verb 'List' is specific and the resource is precisely named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to see generated content, including both drafts and published, and it directs users to prefer this tool over reconstructing results from briefs. It also tells users to use 'kind' to filter. It lacks explicit exclusions for when not to use it (e.g., when you need a single blog article detail), but the guidance is sufficient for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the write action and the follow-up polling, but doesn't say whether the list replaces existing mediums, what the response/return value is, or failure/error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose and step number; every sentence provides actionable workflow guidance without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple but has no output schema. The description provides essential workflow context (when to call, what comes next) but omits return value and overwrite semantics, so slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; both brandId and mediums are described. The description only restates the mediums meaning ('platforms the brand publishes on') and adds no new parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('saves') and resource ('list of platforms the brand publishes on'), and labels it as 'STEP 2 of brand onboarding,' which clearly distinguishes it from read-only siblings like get_brand_mediums.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit instructions: call immediately after create_brand/onboard_brand and after user picked platforms; then poll get_onboarding_status until done. This is precise when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explicitly discloses the bulk-replace/overwrite behavior, which is important. But it does not mention irreversibility, permissions, or what happens to existing cards beyond 'replace'. This 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary action, and contains no filler or repetition. Every word contributes to understanding the tool's purpose and input expectations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 3 parameters and a fully described input schema, the description provides the core replacement semantics and input shape. It doesn't explicitly cover rerender or output, but those are visible in the schema and are not critical for selecting the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, giving a baseline of 3. The description adds meaningful semantic detail by specifying that card objects contain 'title, body, and optional number', which clarifies the expected structure beyond the schema's property list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Bulk-replace') and clearly identifies the resource ('all carousel cards for a post'). It distinguishes itself from sibling tools like list_post_cards (read-only) and edit_post_card (single-card edit).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this is for full replacement by saying 'Provide a full array of card objects', which differentiates it from single-card editing. However, it does not explicitly name alternatives (e.g., edit_post_card) or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explains that the default return is the full strategy and all line items, and that detail levels provide different verbosity (compact summary, or just id/status plus count). This is useful behavioral context, but it does not mention potential side effects (though fetching is likely safe) or permissions, which would make it more complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and then efficiently explains the details of the detail parameter. No fluff or redundant repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a fetch tool with no output schema, the description explains the different return shapes based on the detail parameter, which covers the main variations. However, it does not describe the exact structure of the 'full' response (e.g., whether it is an object with 'strategy' and 'lineItems' fields), which would be helpful given the absence of an output schema. Still, the description is reasonably complete for the tool's simple read purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage, so the baseline is 3. The schema already describes the detail parameter thoroughly, including what 'short', 'medium', and 'full' return. The description adds a tool-specific note about the line-item count in 'short', but this is marginal over the schema's explanation. The other parameters (brandId, storylineId) are adequately covered by the schema, so the description does not need to add more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Fetch the strategy and line items for a storyline.' This is a specific verb+resource combination that distinguishes it from sibling tools like storyline_get (which likely fetches base storyline info) and storyline_edit_strategy (which modifies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames when to use this tool: when needing the strategy and line items for a storyline. It also explains the default full detail and the effects of the detail parameter, giving context for different use cases. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It clearly states the operation is a full replacement ('replace the full brief') and introduces the expectedVersion parameter for optimistic concurrency, explaining that 0 is used when setting from scratch. It also discloses that confirmation is a separate step, preventing the agent from assuming this tool triggers strategy generation. This is strong behavioral disclosure for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences precisely deliver purpose, usage, and workflow. The first sentence front-loads the primary action, the second provides parameter guidance, and the third gives the next step. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with a nested brief object and concurrency control, the description covers the core workflow: replacing the brief, passing the complete object, using expectedVersion, and following up with storyline_confirm_brief. It lacks an explicit mention of return values or error conditions, but given the absence of an output schema and the detailed schema, this is a reasonable trade-off.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds 'complete brief object' reinforcing that the entire brief must be passed, and reiterates the expectedVersion semantics already in the schema. Beyond that, it does not deeply expand on parameters because the schema already provides detailed descriptions for the nested brief structure and concurrency version.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Manually set (replace) the full brief for a storyline.' This clearly differentiates from sibling tools like storyline_edit_brief or storyline_update by emphasizing full replacement. It also provides concrete use cases ('provide a human-authored brief or to push back an edited version retrieved via storyline_get'), 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use when you have a complete human-authored brief or when pushing back an edited version from storyline_get. It also instructs to call storyline_confirm_brief afterward, defining the next step. However, it does not explicitly mention alternatives like storyline_edit_brief for partial updates, so exclusion guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: the precedence of 'templates' over single fields, support for one or many records, and the return value. It does not mention authentication, idempotency, or side effects beyond creation, but the most important operational details are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are front-loaded with the tool's purpose, followed by concise instructions on single/bulk usage, precedence, and return value. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 9 parameters and rich schema, the description is adequately complete. It covers both creation modes, precedence, and return value. The schema handles field-level details, and while an output schema is absent, the mention of returning created record(s) helps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with detailed parameter descriptions, so the description adds limited value here. It clarifies the relationship between top-level fields and the 'templates' array, but the schema itself documents required fields and defaults. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create one or more content templates for the brand' with a specific verb and resource. It distinguishes from sibling tools like template_list, template_update, and template_delete by emphasizing the create action and the added bulk-creation capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use the tool, including the choice between single and bulk creation and an explicit precedence rule. It does not explicitly name alternative tools for update/delete or state when not to use this tool, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It effectively discloses the synchronous execution, the side effect of saving when save=true, and the return value ('Returns the extracted template object; if saved, includes the new template id'). It does not mention auth requirements or error cases, but covers the essential behavioral traits for this simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, immediately starting with the core purpose. Every sentence provides necessary information: what it does, the synchronous nature, and the save/return behavior. There is no redundancy or filler, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters and no output schema, the description covers the main aspects: operation, timing, optional saving, and return value. It could mention the default brandId behavior or error scenarios, but these are minor gaps given the tool's simplicity. The overall context is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds some value by explaining the outcome of save=true ('also persist the template to the brand's library') and the resulting template id, but it does not add meaning for postText or brandId beyond what the schema already states. The schema remains the primary source for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'AI extracts a reusable content template from a pasted post text.' It uses a specific verb ('extracts') and resource ('content template from pasted post text'), distinguishing it from sibling tools like template_create and template_pick. The purpose is unambiguous and directly tied to the tool's name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool by stating it is synchronous ('Synchronous (seconds) — no polling needed'), which guides the agent away from polling. It also explains the optional save behavior ('Pass save=true to also persist'). However, it does not explicitly mention alternatives or exclusions (e.g., when to use template_create instead), so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It adds useful output details (previewUrl logic, sectionKeys/sectionWordCounts for medium) but does not explicitly state that this is a read-only operation, nor does it mention authentication, rate limits, or potential errors. The verb 'View' implies safety, but the description stops short of full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, directly front-loaded with the purpose. The second sentence packs the detail-level behavior efficiently without redundant language. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides a reasonable picture of the return data for full and medium, and the schema's detail parameter covers 'short.' The provenance of versionId is explained in the schema. It doesn't describe error cases or permissions, but for a read view tool with strong schema coverage, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by explaining what the detail levels return: 'full' returns previewUrl, 'medium' adds sectionKeys/sectionWordCounts. This gives functional meaning beyond the enum's generic 'verbosity' explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'View a specific LP version,' providing a clear verb+resource pair. It explicitly targets a single version, distinguishing it from sibling tools like list_lp_versions, view_lp_draft, and restore_lp_version. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames the tool as the go-to for viewing one specific landing page version, and schema field versionId states it should come from list_lp_versions, implying a workflow. It does not explicitly name alternatives or provide when-not conditions, but the context is clear enough for an agent to differentiate it from listing or mutating versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly indicates a read-only operation ('View') and enumerates the exact return structure for each detail level, which adds transparency beyond a generic 'view' statement. It does not cover error handling or permissions, but for a simple read tool, the disclosure is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the purpose is front-loaded, and the detail variations are compactly listed in a single sentence. Every clause earns its place, avoiding unnecessary fluff while conveying essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no output schema, so the description must serve as the de facto output specification. It does this thoroughly by describing the exact shape of full, medium, and short responses. It lacks error handling or authorization details, but for a straightforward view operation, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% parameter coverage with descriptions, so the baseline is 3. The description adds value by specifying what each detail level returns for this specific tool (full, medium, short), which goes beyond the generic schema description of the detail enum. This extra context helps agents choose the right verbosity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'View a specific side-page version snapshot.' This is a specific verb+resource that distinguishes it from siblings like view_side_page (current side page) and view_lp_version (landing page version). The inclusion of return formats further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 like view_side_page or list_side_page_versions. Usage is implied by the requirement of versionId, but there are no stated exclusions or named alternatives. The detail parameter guidance is present but only covers verbosity levels, not tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the tool's return content (email, plan, credit balance, token source) and indicates it operates on the current authenticated user, implicitly a read-only operation. However, it does not explicitly state that no changes are made or describe failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 result. It contains no redundant words and every piece of information (return value and included fields) earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description is reasonably complete. It specifies the exact profile fields returned but does not specify the response format (e.g., JSON shape) or any potential error conditions. Given the simplicity of the tool, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no further parameter details, but none are needed. Schema coverage is 100% (empty properties) and the description correctly indicates no inputs are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Return' and clearly identifies the resource as 'the profile of the currently authenticated PostKing user'. It explicitly lists what the profile contains (email, plan, credit balance, token source), which distinguishes it from siblings like get_credits or billing_wallet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'currently authenticated' implies it should be used after login, but there is no explicit guidance on when to use this versus related tools like get_credits or list_api_keys. The usage context is clear from the tool name, but no alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the different output detail levels (short, medium, full), the default behavior (short), and the tag filter's flexibility (array or comma-separated). It does not mention pagination or latency, but for a list tool the provided behavioral details are solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient, packing purpose, output format details, filtering options, and a usage pointer into two sentences. It is front-loaded with the primary action and resource, and every clause earns its place. Slightly longer than ideal but still concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 7 optional parameters and no output schema, the description is substantially complete: it explains the three detail levels, default behavior, filtering dimensions, and directs to the get tool for full item details. It lacks explicit notes on sorting or pagination, but these are not part of the schema and the essentials are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 7 parameters with detailed descriptions, so the baseline is 3. The description adds genuine value by explaining what each detail level returns (e.g., 'short {id,name,type,pinned}') and clarifying the tags parameter's dual array/comma-separated format, which goes beyond the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists the brand's stored brand truths and defines them as 'atomic facts/observations used to ground generation'. It specifies the verb 'list' and the resource, and differentiates from sibling tools by explaining the output detail levels and the guidance to use a get/view tool for full details on one item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it's for listing brand truths with optional filters, and explicitly notes that lists default to 'short' and that to zoom into one item you should call the get/view tool with detail='medium' or 'full'. It stops short of naming the exact sibling tool (brand_truth_get), but the guidance is unambiguous enough to steer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does an excellent job: it discloses async behavior, return format, the need to poll get_job, side effects (crawl + profile analysis per domain), and expected duration. This is far beyond a minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: async nature, batch scope and target, return format and polling, side effects and timing. No redundancy or filler. Front-loaded with the most critical 'Async' requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async batch operation with no output schema, the description is complete: it explains how to invoke, what to expect (operationId, status), how to track completion (poll get_job), what will happen (crawl + analysis), and typical latency. It provides enough context for an agent to use correctly and know what to do next.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of parameters with descriptions, providing a baseline of 3. The description adds behavioral context (each domain triggers analysis) but does not add new parameter semantics beyond what the schema already states. Both brandId and domains are adequately described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear, specific verb 'batch-add' with resource 'competitor domains' and target 'brand'. Distinguishes from sibling tools like competitor_probe or competitor_update by emphasizing the batch add behavior. Even without naming alternatives, the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for adding multiple competitor domains and explains the async polling flow, but it does not explicitly state when not to use this tool or mention alternative tools like competitor_probe for single-domain tasks. This is sufficient for a clear context but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does well by disclosing the async nature and return behavior: 'Returns { started: true } when kicked off, or { alreadyRan, status } when a probe result already exists.' Also hints at the crawling behavior. It doesn't detail internal side effects but enough for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action, then return values, then workflow. No filler or repetition; every sentence adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's role in the workflow: start, poll, classify. It explains return values inline and notes idempotency. For a simple async trigger with one optional parameter, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the only parameter brandId is 100%, and the schema already describes it as 'Brand ID (defaults to active brand)'. The description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Start a competitor discovery probe', using a specific verb and resource. It clearly distinguishes this tool from related siblings by explaining it initiates the process, while competitor_probe_status polls and competitor_probe_classify handles candidate acceptance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: it's for automatically finding rival domains via web crawling, and outlines the next steps (poll status, then classify). However, it doesn't explicitly state when to prefer manual alternatives like competitor_add, or mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses behavioral traits: it is asynchronous, returns { operationId, status }, requires polling get_job until state=completed, and takes ~2–5 minutes. This gives the agent a clear operational picture beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the core purpose front-loaded ('Async. Refresh all active competitors...') and the second sentence providing return format and polling instructions. Every word earns its place with no unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async operation with one optional parameter and no output schema, the description adequately covers the return value, monitoring procedure, and expected runtime. It provides sufficient information for an agent to invoke the tool and follow up via get_job.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for brandId, including its default behavior. The description does not add additional meaning about the parameter, so the baseline score of 3 applies as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Refresh all active competitors for the brand (re-crawl + re-profile).' It specifies the verb (refresh), resource (active competitors), and scope (all for the brand), distinguishing it from sibling tools like competitor_analyze or competitor_probe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about the async nature and typical runtime (~2–5 min), implying when to use it (when refreshing all active competitors). However, it does not explicitly mention alternatives or exclusion criteria compared to other competitor_* tools, so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It explicitly states the non-destructive nature ('without deleting it') and reversibility ('Re-enable later'), which are key behavioral traits. It does not mention side effects or permissions, but for a simple pause operation, the disclosure is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action verb. No wasted words; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one optional parameter, no output schema, and a straightforward action. The description fully explains the purpose and the relation to enable_weekly_schedule, making it complete for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (brandId) is fully described in the schema with 'Brand ID (defaults to active brand)', so schema coverage is 100%. The description adds no additional parameter context, which is acceptable given the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (pause) and the resource (weekly content schedule), and explicitly contrasts with deletion ('without deleting it'), distinguishing it from the sibling tool delete_weekly_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it ('Pause... without deleting it') and names the re-enable alternative (enable_weekly_schedule). However, it does not explicitly mention delete_weekly_schedule as the alternative for permanent removal, though the contrast with deletion is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it discloses the default response shape ('slim option list with pickArgs'), the behavior of each detail level, and the conditional inclusion of 'editInVisualEditor' when an active brand is set. This is substantial behavioral transparency, though it does not explicitly state that the operation is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is six sentences, each adding distinct information (purpose, return types, related tool, default behavior, detail variations, conditional field). It is front-loaded with the primary purpose and remains compact without redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description does a good job enumerating key output elements (bestPick, categorized options, pickArgs, editInVisualEditor) and the effect of the detail parameter. It could be more explicit about the overall response structure or error handling, but it covers the tool's main behavior sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, so baseline is 3. The description adds meaningful semantics for the 'detail' parameter by explaining the default ('medium') returns a slim list with pickArgs, 'short' for counts only, and 'full' for raw catalog. No additional explanation is needed for 'postId', 'category', or 'platform'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch available visual options for a post' and enumerates content types (card templates, library matches, stock photos), distinguishing it from sibling tools like pick_post_visual by noting that one must be used to apply an option. It is specific about the verb and resource, and the scope per platform clarifies the function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance to 'Use pick_post_visual to apply one of the returned options', which clarifies the follow-up action. It also gives parameter-specific advice for 'detail' values. However, it does not mention any cases where another tool (e.g., search_stock_images) would be preferred, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly indicates this is a read operation returning specific fields, and it is transparent about the 'slim summaries' nature, though it doesn't dive into error handling or pagination—which are not critical for this simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and packs a lot of useful information without fluff. The field list is long but necessary to convey the return shape, and the alternative tool references are valuable. It's slightly dense but still well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with optional parameters and no output schema, the description provides enough context about the return value and gives pointers to sibling tools. It covers core fields and mentions counts, which is sufficient for an agent to know what to expect. Minor gaps like auth requirements are not mentioned but are less critical here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds context about the return structure and hints at the level of detail, but it does not substantially elaborate on parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a brand's profile and enumerates the specific return fields. It distinguishes itself from sibling tools by explicitly mentioning that full detail is available via dedicated list tools, giving a unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to use list_themes, list_voices, list_blog_authors, list_posts, or get_brand_members for full detail, making it clear when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently explains the default output (final voice-rewritten content), the includeOriginal option for pre-rewrite drafts, the variations array behavior, and the presence of contentReviewUrl and editInVisualEditor. It stops short of explicitly stating that the operation is read-only and does not discuss failure modes, but 'View' and 'get_post' strongly imply a non-mutating read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the main purpose, and each sentence adds a distinct detail. Some repetition of schema defaults (e.g., 'default full', 'default false') exists, but the description remains tight and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description covers the essential output aspects: content, status, verbosity control, variations, original content toggle, and review/edit URLs. It does not detail the full structure of 'short'/'medium'/'full' outputs, but the schema's detail enum covers that, making the description sufficient for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful behavior beyond the schema: it explains the default 'full' verbosity, the variations array semantics for multi-variation posts, and the includeOriginal flag's effect on output. This exceeds simple schema repetition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'View the full content and status of a single post,' using a specific verb ('view'), resource ('post'), and scope ('single') that clearly distinguishes it from list-oriented tools like list_posts. It also specifies distinct features (variations array, includeOriginal, contentReviewUrl, editInVisualEditor) that further clarify its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'single post' wording makes the primary use case clear, and the detail parameter guidance ('Lists default to short — to zoom into one item, call its get/view tool') explicitly tells agents when to use this tool over list tools. However, it does not directly mention alternatives for editing/deleting (e.g., approve_post, delete_post), though those are contextually obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the return fields (enabled status, lead time, timezone, per-day configs), the default-value behavior when no schedule exists, and the viewInBrowser link. This gives a good sense of what to expect without needing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and front-loaded with the primary purpose. Each sentence adds distinct value: what it retrieves, what it returns, and the default behavior plus link. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no output schema and two optional parameters, the description is complete. It covers return content, edge case (no schedule), and a UI link, making it sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (detail, brandId) have thorough descriptions in the schema. The tool description adds no additional parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the current weekly content schedule for the active brand, using a specific verb and resource. It distinguishes itself from sibling tools like enable_weekly_schedule, disable_weekly_schedule, and set_weekly_schedule by focusing on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it's for reading the schedule, and mentions behavior when no schedule is configured (returns suggested defaults). It doesn't explicitly name alternatives or exclusions, but the read vs. write distinction from sibling tools is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses the asynchronous behavior, expected duration (~1-3 min), and return shape ({ operationId, status }). It also clarifies the workflow's purpose (repurpose to Reddit), which adds context beyond the raw operation, though it does not state potential side effects or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, then timing/returns, then workflow/context. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter async generation tool with no output schema, the description explains the return value, the polling pattern, and the follow-up call, plus the workflow context. This is sufficient for an agent to use the tool correctly and know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the only parameter brandId (including default behavior), achieving 100% schema coverage. The description names the brand but does not add any extra semantic detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Kick off') and resource ('subreddit pool for the brand'), clearly distinguishing this async generator from sibling tools like reddit_get_pool (which retrieves results) and reddit_suggest (likely a suggestion tool). It also explains the underlying mechanism (crawling Reddit) and the brand context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: it explains the async flow (poll get_job until completed, then call reddit_get_pool) and clarifies when NOT to use it (not a scheduled publishing medium). It does not explicitly contrast with all sibling tools but gives enough context to know when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses pagination behavior ('Cursor-paginated') and the exact return shape, including the outputData schema. While it doesn't explicitly state there are no side effects, the term 'List' and the nature of the operation imply a read-only behavior. It adds meaningful context beyond the schema with the return format and flow position.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and efficient, with three sentences that cover purpose, pagination, return format, outputData contents, and flow context. Every sentence serves a distinct purpose with no redundant or ambiguous wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description provides a comprehensive return structure including nested outputData fields. The flow context and pagination details make it complete for an agent to understand what the tool does and what to expect. There are no significant gaps for a list/pagination tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (limit, cursor, brandId) is already well-documented. The description adds a little value by explaining the cursor-pagination mechanism and the nextCursor link, which ties limit and cursor together. However, it doesn't provide additional semantics beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'List' and the resource 'saved Reddit posts', and explicitly identifies them as outputs of reddit_rewrite. This distinguishes it from sibling tools like reddit_rewrite, reddit_suggest, and reddit_get_pool. The flow step naming also reinforces its specific role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description places the tool in a sequential flow: pool → suggest → rewrite → LIST_POSTS, which implies it is the final step to retrieve saved rewritten posts. It doesn't explicitly state when not to use it or name alternatives, but the flow context provides solid guidance for when this tool should be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden — and it succeeds richly. It discloses async timing ('~30–90 sec per variation'), the dual return path (inline finished post vs postId + 'still in progress'), the polling requirement, the concurrency guard, and the subreddit-not-onboarded edge case that yields a `subredditNotice`. This is exemplary for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is roughly 120 words across four sentences, but every sentence earns its place: purpose, latency, async/return behavior, polling + do-not-repeat, and the subreddit-notice edge case. It is front-loaded with the most critical facts (async, purpose) and remains efficient given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter async tool with no output schema, this description covers the full user contract: purpose, latency, return paths, polling target, concurrency guidance, and edge-case behavior. It does not describe the structure of the returned Reddit post or enumerate other operationStatus values, but the essential interaction is thoroughly specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — every parameter (subreddit, sourcePostId, sourceContent, variations, etc.) already has a meaningful description. The tool description adds behavioral context around the subreddit parameter (non-pool handling) but no new parameter-level semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+outcome: 'Rewrite a blog article (or raw content) into a Reddit-native post for a specific subreddit.' It further differentiates from siblings by stating 'Flow step 3 of 4: pool → suggest → REWRITE → list_posts', explicitly positioning this tool as the rewrite stage rather than the suggest or list stages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit exclusion ('Do NOT call reddit_rewrite again for the same request while it's pending') and an explicit alternative ('Poll get_post with that postId until operationStatus is COMPLETED'). The flow-step note implies natural usage timing, but it does not compare against generic rewrite tools like rewrite_text or generate_post, so it misses some alternative-context guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It openly states the failure condition when briefs already exist, which is a key behavioral trait not visible in the schema. It also implies a mutation operation. While it does not mention permissions, idempotency, or return values, the disclosed information is highly relevant and valuable for this state-transition tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with the primary action. The second sentence immediately provides a critical limitation without fluff. Every word earns its place, and the structure is clear and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (two parameters, one required, no output schema, no nested objects), the description is complete. It explains the core state change and a critical precondition/failure mode. The description is sufficient for an agent to understand the tool's purpose and constraints without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both parameters (brandId and clusterId), covering 100% of the schema descriptions. The tool description does not add additional parameter-level meaning beyond what the schema states. Therefore, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Revert an approved cluster back to pending_review') with a specific verb and resource, making it unambiguous. It also distinguishes itself from sibling tools like seo_reject_cluster and seo_restore_cluster by defining the exact state transition. No ambiguity or tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to undo an approval and return a cluster to pending_review. It also provides an important exclusion/limitation ('Fails if briefs have already been generated'), which guides usage. However, it does not explicitly name alternative tools or provide broader 'when not to use' guidance beyond the briefs condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It indicates the behavior is a read-only check ('Check') and describes the return value, which is sufficient for a low-risk verification tool. It does not detail permissions or side effects, but none are expected for a check operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences or one compact sentence, front-loading the main action and providing essential detail without any fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description fully covers the purpose, the return behavior, and even hints at the source of the domain ID via the schema. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, domainId, already has a clear schema description ('Domain ID to verify (from list_domains)'). The description adds no extra parameter information, so it matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Check DNS verification for a domain.' It also specifies the output ('Returns whether it's pointing to PostKing servers and what A record is needed if not'), distinguishing it from sibling domain tools like add_domain or delete_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context that this tool is for verifying DNS status, implying when to use it. However, it does not explicitly mention alternatives or when not to use it, lacking the exclusionary guidance seen in high-scoring examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that section bodies and rendered HTML only appear at 'full', and explains the included previewUrl/webUrl fields. It implies a read-only operation via 'fetch' but does not explicitly state non-mutation, though this is acceptable for a fetch tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence with semicolon-separated clauses. The purpose is front-loaded, and every clause conveys necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-param tool without an output schema, the description covers the main return variants and their differences. It does not mention error cases or authorization, but these are less critical for a read-based fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds significant value by detailing exactly what each detail level returns (e.g., medium = summary + sectionKeys/sectionWordCounts), far exceeding the schema's generic 'Verbosity' phrasing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb 'Fetch' and resource 'landing page by slug', clearly identifying the operation. It does not explicitly distinguish from sibling view tools (like view_lp_draft or view_lp_version), but the purpose is unambiguous without crossing into tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on how to choose between 'full', 'medium', and 'short' detail levels, including what fields each returns. It does not mention alternatives to this tool, but the detail-level context is enough for most selection decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It explicitly reveals the side effect: 'This also records rejection memory: the system learns to stop re-suggesting that fact during future extractions.' It also warns about the unintended consequence of permanent learning. This goes beyond the basic delete action and is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary purpose, followed by the side effect and a cautionary note. Every sentence earns its place with no fluff or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 parameters, no output schema), and the description covers purpose, side effects, and usage caution. However, it does not mention expected return behavior or error cases, which could be helpful. This is a strong description for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both 'id' and 'brandId' having descriptions in the schema. The description adds no new parameter meaning beyond the schema, only reaffirming 'by ID.' The baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a brand truth by ID.' It specifies the verb (delete), the resource (brand truth), and the scope (by ID). This distinguishes it from sibling tools like brand_truth_update or brand_truth_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool: 'Use it deliberately — deleting a truth teaches PostKing that the fact should not come back.' This signals caution and explains the irreversible learning side effect, but it does not explicitly name alternatives or exclusions (e.g., 'use update instead to retain but modify').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the behavior of the detail parameter by listing exact fields for short and medium, and describing full as raw with full content. This gives the agent a good sense of what to expect in the response, though it does not address error cases or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence with no filler. It front-loads the core purpose and then efficiently enumerates the detail level differences, earning its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with no output schema, the description provides a reasonable outline of the return values for short and medium, and indicates full contains raw content. It is not exhaustive (e.g., 'raw' is left somewhat ambiguous), but it covers the essential behaviors needed to select the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema covers 100% of the parameters, the description adds value by concretizing what each detail level returns: short has specific fields, medium adds specific fields, and full includes the complete body. The schema only describes the enum values abstractly, so this extra detail is helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Fetch a single brand truth by ID.' It clearly distinguishes from sibling tools like brand_truth_list by emphasizing 'single' and 'by ID.' The mention of detail levels adds further clarity about the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 you need a single brand truth by ID. It explains the detail levels and explicitly recommends detail='full' for retrieving the complete content body. However, it does not explicitly name alternatives (e.g., brand_truth_list), relying on the purpose to imply the contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral trait: 'it writes the provided fields directly' and 'does NOT re-run the LLM extraction pipeline', which is valuable beyond the schema. However, it doesn't explicitly state that unspecified fields are left unchanged or describe return values, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action and target. Every sentence serves a purpose: scope, key behavior, use cases, and alternative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter mutation tool with no annotations and no output schema, the description gives a solid mental model: targeted edit, direct write, partial update implied, and clear alternative. It could be more explicit about unspecified fields remaining unchanged, but the description is generally sufficient for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description groups parameters by use case ('correct wording (name/description/content), fix the type/personaScope, adjust tags, or pin/unpin'), which adds a little semantic context, but it doesn't explain anything about parameters that the schema doesn't already cover.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Targeted edit of an existing, known brand truth (by ID)', a specific verb+resource combination. It clearly differentiates from siblings by stating it does NOT re-run the LLM extraction pipeline and pointing to brand_truth_create for new facts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states what to use it for: correcting wording, fixing type/personaScope, adjusting tags, pin/unpin. Provides a clear alternative: 'To capture NEW facts from prose, use brand_truth_create instead.' This gives unambiguous when-to-use vs when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses side effects: flips to cancelled, stops polling, in-flight work may finish but result discarded, finished jobs cannot be cancelled. This is thorough and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with verb and object, then consequences, then usage tip. Every sentence contributes and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a cancellation tool, the description addresses lifecycle states and polling behavior. It does not describe the response format, but no output schema exists; given the simplicity, this is acceptable. The optional brandId is left to the schema, which is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds context for operationId source ('from list_jobs pollUrl / get_job') but no new semantics beyond schema. brandId is only described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Cancel a pending or running job/operation' with specific behavior ('Flips it to `cancelled` and stops it from being polled'). It distinguishes from sibling tools like cancel_post by targeting jobs/operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: applies to pending or running jobs, not already-finished ones. Instructs to pass operationId from list_jobs pollUrl or get_job. Lacks explicit alternative names, but the context implies this is the dedicated cancellation tool for operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly discloses the null return behavior when no comparison exists, and specifies the output structure for each detail level (short, medium, full). This is transparent about a key edge case, though it doesn't mention potential errors or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single purpose sentence, a compact overview of detail levels, and a final sentence on null handling. Every sentence delivers unique information without verbosity or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description compensates by detailing return structures and null behavior. It provides enough context for the agent to invoke the tool correctly, though it could further clarify the distinction between this and competitor_get_overview. Overall, it is sufficiently complete for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters thoroughly (100% coverage), so the baseline is 3. The description adds value by specifying concrete response fields for each detail level (e.g., generatedAt, competitorCount, strengths, weaknesses) not present in the schema's generic descriptions. This enhances the agent's understanding of what each detail setting returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the brand's head-to-head competitive comparison.' It uses a specific verb ('Get') and resource ('head-to-head competitive comparison'), distinguishing it from siblings like competitor_recompute_comparison by noting the null case and the alternative action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: when a comparison hasn't been generated, it returns null and directs the agent to use competitor_recompute_comparison. It also explains the detail levels to help select the appropriate verbosity. However, it doesn't explicitly contrast with other competitor tools like competitor_get_overview, which would strengthen the guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It transparently reveals that the tool saves a draft (not directly schedules), mentions that each created post includes an editInVisualEditor URL, and points to the approve_post step for scheduling. It does not cover permissions or side effects, but the creation behavior is sufficiently clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the primary purpose, and each sentence adds distinct value (function, platforms, next steps, special return field). There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description supplies key return information (editInVisualEditor URL) and workflow context (approve_post, check_social_accounts). One minor gap is that the schema includes a scheduledAt parameter for immediate scheduling, which the description does not mention, potentially causing slight ambiguity. Overall, it is fairly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and every parameter (brandId, content, platforms, scheduledAt) already has a description. The description reiterates the supported platforms but adds no new parameter-level meaning beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Save a post draft with custom content to one or more platforms.' It also lists the exact supported platforms and distinguishes itself from related tools like approve_post and check_social_accounts by explaining the post-creation workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow guidance: 'After creating, call approve_post with a future ISO 8601 datetime to schedule it' and advises checking connected platforms first via check_social_accounts. This clearly defines when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool returns a link and adds a critical caveat about the non-existent '/seo/roadmap' page, which is valuable context. However, it does not mention authentication or error behavior for invalid sections, though these are less critical for a simple link generator.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, with the core purpose front-loaded in the first sentence and a valuable usage instruction in the second. Every sentence earns its place, with no filler or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and the well-structured enum schema, the description covers the essential behavior and the critical section mapping caveat. The phrase 'clickable browser link' sufficiently indicates the return type. It omits edge-case details like brand validation, but these are not essential for this simple utility. It achieves near-complete guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters having descriptions, so the baseline is 3. The description reinforces the 'seo_briefs' mapping, but this information is already present in the schema's 'section' description ('SEO roadmap/content plan → seo_briefs. Reddit module → reddit.'). The description adds limited new parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific action ('Return a clickable browser link') and a clear resource ('PostKing dashboard page'), making the tool's purpose unambiguous. It further distinguishes itself from siblings by explicitly stating it should always be used instead of guessing dashboard URLs, establishing it as the designated link generator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'ALWAYS use this instead of guessing dashboard URLs.' It also clarifies the correct section for the SEO roadmap/content plan ('seo_briefs'), preventing misuse of the tool and guiding correct parameter selection. No alternatives are needed since this is the sole tool for dashboard links.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly discloses a key behavioral boundary: 'Does NOT touch page content.' This goes beyond the tool name and gives the agent essential safety information. However, it does not mention whether the update overwrites or merges with existing metadata, nor does it describe any authentication or return behavior. For a simple metadata update, the disclosed boundary is significant, but other behavioral details are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the most important constraint ('METADATA ONLY') and immediately follows with the exclusion of content. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with three parameters and no output schema, the description covers purpose, exclusions, and alternatives thoroughly. It omits return value semantics and any note about whether the tool requires an existing landing page, but these are relatively minor gaps given the tool's simplicity and the surrounding sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters (slug, title, instructions). The description adds no additional parameter-level meaning beyond repeating 'title and/or instructions.' Since the schema already documents each parameter, the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') with a clear resource ('landing page') and explicit scope ('METADATA ONLY — title and/or instructions'). It directly states what the tool does and distinguishes it from content-editing siblings by emphasizing 'Does NOT touch page content.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: use for metadata-only updates. It also names two alternatives for content changes (set_landing_page_section and vibe_edit_landing_page), making the tool's place among siblings clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It thoroughly explains the return contents for each detail level and the effect of maxContentChars. However, it does not explicitly state that the operation is read-only or describe error behavior, though 'fetch' implies safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, starts with the core action, and efficiently conveys the detail levels and maxContentChars guidance. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with no output schema and no annotations, the description covers the key behaviors: detail verbosity, field lists, and payload bounding. It does not mention brandId or error cases, but given the 100% schema coverage, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning beyond the schema by enumerating the exact fields returned for each detail level and clarifying the purpose of maxContentChars. It does not discuss brandId, but the schema already covers it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Fetch a blog article by ID,' which is a specific verb and resource. It clearly distinguishes from sibling tools like update_blog_article, delete_blog_article, and list_blogs by focusing on single-article retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching one article and provides explicit guidance on when to use maxContentChars ('only if you need to bound the body size'). It does not explicitly name alternatives like list_blogs for listing multiple articles, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool polls background analysis + theme generation, describes output granularity per detail level, and advises polling frequency. It does not explicitly state whether the operation is read-only or has side effects, but 'Polls' strongly implies a non-mutating status check, and the completion guidance adds actionable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the purpose, then detail semantics, then operational guidance. No filler. Each sentence earns its place and the structure flows logically from what/why to how/actions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple polling tool with optional parameters and no output schema, the description adequately covers invocation, detail-level variations, polling rate, and post-completion action. It doesn't describe error states or exact response shape for 'full', but the provided field-level detail (audienceSummary, themeCount) gives enough context for an agent to invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described, but the tool description adds critical meaning by explaining what each detail enum value returns ('short' = status only, 'medium' = adds audienceSummary+themeCount, 'full' = raw data). This goes beyond the generic schema description of 'detail' and helps the agent select the appropriate verbosity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's function: 'STEP 3 of brand onboarding. Polls background analysis + theme generation.' It uses a specific verb ('Polls') and resource (onboarding status), and distinguishes from status tools for other workflows (e.g., get_blog_status, get_vibe_edit_status) by targeting this onboarding step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: it is Step 3, to be polled, and gives a concrete polling interval ('every ~15s'). It also tells the agent what to do when done ('surface the audience review + themes to the user'). It lacks explicit mention of alternatives or when not to use it, but the specificity of 'STEP 3 of brand onboarding' makes the usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that 'The server fetches and stores the file' and clarifies that assetType is 'recorded as a tag on the asset to preserve provenance.' This goes beyond the basic action and explains important side effects, though it does not cover permissions, failure modes, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the core action, and the second provides targeted guidance for a specific parameter. It is front-loaded, efficient, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, one required, and no output schema. The description covers the import process and the one nuanced parameter (assetType), which is sufficient for basic usage. However, it omits any mention of return values or common error conditions, which would make it more complete given the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (80%), so the baseline is 3. The description adds value by explaining the assetType parameter in detail: when to set it (for search_web_images results) and its storage semantics (recorded as a tag). This exceeds the schema's simple 'source-provenance' description. Other parameters rely on the schema, which is acceptable given high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Import an asset into the brand library from a public URL.' It uses a specific verb ('Import') and resource ('brand library'), and the second sentence adds a distinct use case (importing search_web_images results) that differentiates it from generic upload or CSV import tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use this tool (when you have a public URL) and specifically instructs when to set assetType ('when importing a result surfaced by search_web_images'). However, it does not explicitly name alternative tools like upload_asset or import_assets_csv or state when not to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It transparently explains the varying return shapes for each detail level ('short', 'medium', 'full') and explicitly advises using detail='full' to get the complete content body. This goes beyond the schema's generic 'complete object' phrasing. However, it doesn't address failure modes or error behavior, but for a simple fetch that's acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and every clause provides useful detail. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple get-by-ID pattern, the description covers the main use case and return variations. Without an output schema, the field lists help. It doesn't mention cancellation or error handling, but those are less critical for a read-only retrieval. The detail defaults are implied by schema but the sentence 'Use detail=\'full\'' slightly conflicts with the schema default of 'full', creating a tiny gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds explicit field mappings for short/medium/full, and a directive for using 'full'. This adds value beyond the schema's enum descriptions, though there's a slight discrepancy between the description's 'short {id,name,contentType}' and the schema's 'id + primary label + status', which could cause minor confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a single knowledge-base item by ID', using a specific verb and resource. It distinguishes from sibling tools like knowledge_list, knowledge_create, etc., by focusing on single-item retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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: when you need a single item by ID. It doesn't explicitly name alternatives (like knowledge_list for listings) or mention exclusions, so it lacks an explicit when-not-to-use, but the purpose is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates a read-only listing operation and explains the detail parameter's effect on output (short/medium/full), which goes beyond the schema. It does not explicitly state 'does not modify data,' but 'List assets' conveys non-destructive intent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise, front-loaded sentences that fully convey purpose and key behavior without redundancy. Every sentence contributes useful information, with no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and lack of output schema, the description covers the primary needs: what is listed, how to filter, and what the detail levels return. It omits pagination behavior and ordering, but the limit parameter is documented in the schema, so the description is largely complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so the baseline is 3. The description adds value by explaining the detail parameter's meaning (short=id+type+name, medium=key fields, full=raw) beyond the schema's enum descriptions. It also enumerates filterable fields, reinforcing parameter usage even though it does not explain every parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'List assets in the brand's visual library', clearly stating the tool's function and scope. It distinguishes itself from siblings like view_asset (single asset) and upload_asset (creation) by emphasizing listing and filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and its filtering capabilities (by type, tags, search text), giving clear context for when it would be appropriate to use. It does not explicitly state when not to use it or name alternatives like view_asset, but the listing/filtering framing implies the intended use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains what the tool returns (slots and their current asset assignments), and that slotKeys can be discovered from it. While it doesn't explicitly state read-only behavior, the verb 'List' and the framing strongly imply a safe, non-mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no waste. The first sentence states the core functionality and output, the second adds the key usage guidance and side-page variant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with a complete schema, the description covers the main purpose, output content, and how to inspect side pages. It lacks explicit auth/error behavior, but that is not critical for this straightforward read operation. The absence of an output schema is mitigated by describing what the response includes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing detailed parameter descriptions. The description adds useful context beyond the schema by explaining the purpose of the returned slotKeys and reinforcing the role of sidePageSlug. This elevates it slightly above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing asset slots (placeholders) for landing or side pages, including current asset assignments. It differentiates from the closely related assign_asset_to_slot by explaining this is the discovery step, and from list_assets by focusing on slots rather than assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: 'Use this to discover valid slotKeys before calling assign_asset_to_slot.' It also clarifies the side-page alternative with 'Pass sidePageSlug to inspect a side page's slots.' It doesn't list exclusions or contrast with list_assets, but the primary use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It states the default output (id+name+slug) and the effect of detail='medium', giving insight into return behavior. The 'list' verb implies read-only operation, and no side effects are hidden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the primary purpose in the first sentence and a useful parameter hint in the second. It is efficiently front-loaded and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple list purpose with clear parameter definitions in the schema. The description provides default output and a key variant, while the schema covers the full detail enum. Considering the absence of an output schema and the simplicity of the operation, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% description coverage for parameters, so the baseline is 3. The description adds value by specifying that detail='medium' returns description+articleCount for blog categories, which is domain-specific meaning beyond the generic schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with resource 'categories for a blog publication', clearly distinguishing it from sibling tools like list_blog_authors and list_blogs. It also specifies the default return fields, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states it lists all categories for a blog publication, providing clear context for when to use it. However, it does not explicitly name alternatives or when not to use it, though the domain is apparent 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosures. It explains the meaning of previewUrl, including the distinction between the live version's URL and the ?version= form, plus the top-level previewUrl for the current draft. This is valuable context, though it doesn't cover every potential behavior like ordering or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose, and every sentence adds useful context. No unnecessary words or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the key return value (previewUrl) and its subtle behavior, and points to view_lp_version for further details. It covers the essential aspects for an agent to use the tool correctly, though it could mention array structure or ordering.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters fully with 100% coverage. The description adds nothing beyond restating the default for detail, which is already in the schema. Thus the description provides no substantive parameter information beyond structured data.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List all saved versions of a landing page', clearly stating the verb and resource. It also distinguishes itself from sibling tools by explicitly mentioning view_lp_version for section content, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance to use view_lp_version when section content is needed, which serves as an alternative and a when-not-to-use signal. The default detail='short' and the mention of detail levels also help the agent decide when to use this vs. zooming into a specific version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on the burden of disclosing behavior. It explains the default return format ({index,title}) and the effect of the detail parameter, which is useful for setting expectations. It does not mention error cases or auth, but for a simple read-only list operation, the key behavior is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with no wasted words. The first sentence states the action and resources, the second provides key return behavior. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description compensates by specifying the return format. It includes the relevant context about LinkedIn carousel/PDF generation. It could mention prerequisites like ensuring the post exists, but overall the description is complete for a list operation with two straightforward parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters, but the description adds significant meaning to the 'detail' parameter by specifying exactly what each level returns (default {index,title}, medium truncated body, full all fields). The 'postId' parameter is self-explanatory, so the description adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List') and a specific resource ('carousel cards attached to a post'). It distinguishes itself from sibling tools like edit_post_card and set_post_cards by focusing solely on listing, and adds the context that cards are used for LinkedIn carousel/PDF generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by explaining that cards are used for LinkedIn carousel/PDF generation and by instructing the user on how to control output detail (short/medium/full). It does not explicitly name alternatives or exclusions, but the guidance on detail levels exceeds a bare implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool crawls the site in the background, kicks off potentially async work, sets the brand active (a mutating action), and returns a nextStep payload. It also implies an asynchronous flow, which is useful behavioral context. It could be more explicit about reversible actions or failure modes, but it is substantially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It front-loads the step number and purpose, then succinctly lists actions, return value, and mandatory next steps. Every sentence provides necessary guidance with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and significant side effects (background crawling, audience analysis, brand activation). The description covers the main behaviors, workflow context, and the immediate follow-up steps. It does not detail the nextStep payload structure, but the explicit workflow instructions and warnings make it adequately complete for use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds some context by linking websiteUrl to the crawl action and name inference, but does not go beyond the schema's own descriptions. It does not introduce new semantic details for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is step 1 of brand onboarding via the website path. It specifies the concrete actions: crawling the site, kicking off audience analysis and 10 themes, setting the brand active, and returning a nextStep payload. This distinguishes it from sibling tools like set_brand_mediums and get_onboarding_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames this as the first step in a multi-step workflow. It provides direct sequencing instructions: immediately ask the user about social platforms and call set_brand_mediums, and warns not to call get_onboarding_status until mediums are set. This is clear when-to-use and next-step guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for safety and side effects. It explicitly states 'Read-only helper', which communicates non-mutating behavior. It also discloses that the response is computed from the brand's current audience data, showing an understanding of context. However, it does not mention possible failure modes (e.g., invalid brandId, unparseable prompt) or the exact format of the preview, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each earning its place. The first sentence states the tool's role and when to call it; the second explains the input and how to use the output. There is no fluff or repetition, and key examples of section keys are included inline.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description provides a meaningful picture of the return value (available sections/subsections plus a preview) and gives concrete examples of section keys. It also explains why this tool exists (validation before edit_audience). However, the exact structure of the 'preview' and error/edge-case behavior are unspecified, leaving some completeness gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes both parameters (prompt as a natural-language string, brandId with a default). The description adds workflow context but no new parameter-level semantics. It mentions using the prompt to generate a preview and the returned keys for edit_audience, but this is about output usage, not deeper parameter meaning. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a read-only helper used to discover valid sections/subsections before editing the audience. It specifies a concrete action ('discover', 'returns') and distinguishes itself from the sibling tool edit_audience by explicitly referencing it. The scope is well-defined: it applies to a specific brand's audience data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit instructions: 'Call this BEFORE edit_audience', and explains how to pass a natural-language prompt and use the returned section keys as the required sections array for edit_audience. It clearly situates this tool in a workflow, making the recommended usage unambiguous. No competing tools are mentioned, but the sequencing and integration with edit_audience are concrete enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on the full burden of behavioral disclosure. It discloses that results are sorted most-relevant first, that the pool is brand-level and scored, and that no content is needed. It also clarifies the tool is not a scheduled publishing medium. However, it does not mention potential side effects (though 'Returns' implies read-only), authentication requirements, or what happens if no pool exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. Each sentence earns its place: purpose, use case, alternative tool distinction, and workflow context. It is dense but well-structured with parentheticals and clear emphasis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema, the description covers the core aspects: what it returns, how to use it, how to limit results, and how it fits into the Reddit workflow. It could benefit from slightly more detail about the output shape (e.g., fields returned per subreddit), but the mention of 'each scored' gives useful context. Overall, it is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (top and brandId) with their meanings. The description adds some value by mentioning 'pass top for a top-N list' and 'results are sorted most-relevant first', but this largely mirrors the schema. No additional syntax or format details are provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Returns the brand's pool of relevant subreddits' with a specific verb and resource, and explicitly identifies it as the brand-level subreddit match with scores. It also distinguishes itself from the sibling tool reddit_suggest, which is described as a 'different, content-specific step.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('which/what/top N subreddits should my brand post in?') and when not to, noting that 'NO content needed' and that reddit_suggest is for content-specific steps. It also provides high-level workflow context that Reddit is a repurpose-to-Reddit workflow, not a scheduled publishing medium.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses what happens when the scheduled time arrives: publishes to the PostKing blog and auto-pushes to external platforms flagged autoPublish. It also adds the constraint that scheduledAt must be future. No annotations exist, so the description carries the burden; it covers key behavioral points but does not mention cancellation or what the API returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, then key constraint, then behavioral effect, then alternative. No redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a scheduling tool with no output schema, the description covers core behavior, timing constraint, side effects (auto-push), and alternative. It lacks details about success return value or how to manage the schedule, but is largely complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds only minimal param nuance (e.g., 'existing' article, future datetime) which is also encoded in the schema. The description does not significantly extend schema-provided semantics, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb-resource pair: 'Schedule an existing blog article to auto-publish at a future date/time.' It clearly distinguishes from siblings by naming an alternative for immediate publishing (update_blog_article) and by specifying blog article rather than social posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives a when-not-to-use condition and alternative: 'To publish immediately instead, use update_blog_article with status="published"'. This differentiates from the immediate-publish sibling and clarifies the intended use case for future scheduling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return type ('Returns URLs and descriptions') and explains the effect of the detail parameter in concrete terms ('short=url+thumbnail, medium=adds description+credit, full=raw'). This goes beyond the generic schema description. It does not mention permissions or rate limits, but for a simple search tool, the disclosed behavior is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, output + follow-up action, and detail param mapping. The description is front-loaded with the core action, and there is zero extraneous text. It is efficiently structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough for a search tool with 4 parameters and no output schema: what it searches, what it returns, how the detail param changes the response, and a natural next step (import_asset_from_url). The schema covers brandId and platform. It could mention pagination or licensing, but those are not essential for the tool's primary use. Overall, it is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by translating the generic 'detail' parameter into tool-specific meanings (short=url+thumbnail, etc.), which is not present in the schema's description. This clarifies exactly what the agent can expect at each level. Other parameters are not discussed, but the schema already documents them adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Search stock photo/video libraries for images matching a query.' This clearly distinguishes it from sibling tools like search_web_images, which would target web images. It also states the output (URLs and descriptions) and a follow-up action, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: when searching stock photo/video libraries. It also provides a practical workflow hint ('Use import_asset_from_url to add a result to the library'). However, it does not explicitly contrast with alternative search tools (e.g., search_web_images), which would elevate it to a 5. The context is clear but without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly discloses the precondition that at least one of four fields must be supplied, and it describes the effects of each action: overriding intent, attaching tags, nudging priority, and excluding from clustering. It does not mention authentication requirements, reversibility, or return value, but for a housekeeping edit operation, these are not critical gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with three main sentences and an example. Every sentence adds distinct information: purpose, usage context, precondition, and a practical example. The example is beneficial rather than wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema covers all parameter descriptions and the description provides usage context and a precondition, the tool is well-specified. However, since there is no output schema, it would be helpful to mention what the tool returns, and it does not describe error behavior if the precondition is violated. Still, the essentials for an edit operation are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage, so the baseline is 3. The description adds value by stating the 'at least one of' condition not enforced by the schema and provides a concrete example showing intent and userTags combined, which clarifies how the parameters interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Edit a single SeoScoredKeyword', using a specific verb and resource. The term 'single' distinguishes it from seo_bulk_edit_keywords, and the list of editable fields clarifies scope. While it doesn't name sibling alternatives explicitly, the 'housekeeping op' framing and 'single' provide differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'override the auto-detected intent label, attach user tags, manually nudge priority (0..1), or exclude a noisy keyword from clustering.' It also notes the tool is 'not part of the main flow,' indicating when it should be used. However, it does not explicitly mention the alternative bulk editing tool or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the default returns full detail and specifies exact fields for medium and short detail levels, which is valuable. It does not explicitly state that the operation is read-only or describe error behavior, but the word 'Fetch' implies a non-mutating action and the return detail is thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, starting with the primary purpose and then providing detail options and usage context. It is slightly long due to spelling out field lists, but every sentence serves a distinct purpose, so it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description does a great job of explaining return values for each detail level. It also covers the default behavior and usage context with sibling tools. For a read tool with three parameters, this is complete enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaning by listing concrete fields returned for each detail value, which goes beyond the schema's generic phrases. It also reiterates the default, but the field lists are a meaningful addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a single SeoBrief by id and lists the included content (briefData, status, roadmap item, cluster). It distinguishes itself from the sibling seo_list_briefs by focusing on a single item and from seo_edit_brief/approve by framing it as an inspection step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool before refining with seo_edit_brief or approving with seo_approve_briefs, providing clear context and alternatives. However, it does not explicitly state when not to use it or contrast it with listing tools, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behavioral traits: unpaginated, ID-only, no keyword data attached, and non-primary role. However, it does not mention the potential for large response sizes or any rate-limiting considerations, leaving a minor transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by usage guidance and examples. Every sentence earns its place, with no redundant filler or fluff. The length is justified by the need to explain the tool's niche role and filter compatibility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 16-parameter tool with no output schema and no annotations, the description covers purpose, usage, and examples well. Minor gaps include omitting brandId from the filter list and not specifying the exact response format (though 'ids' is implied). Overall, it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds cross-tool context by referencing seo_list_keywords' filter set, but it inaccurately omits 'brandId' from the list and only illustrates two parameters with examples. It does not meaningfully enhance the schema's per-parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns 'just the ids of every SeoScoredKeyword matching a filter', explicitly distinguishing it from seo_list_keywords by noting 'unpaginated, no keyword data attached'. This is a specific verb+resource+scope articulation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames it as a 'housekeeping op' and provides a concrete use case: selecting all keywords matching a filter, then feeding the returned ids into seo_bulk_delete_keywords or seo_bulk_edit_keywords. It also gives two specific examples (relevanceMax and hasTag), making usage conditions and alternatives clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the default return detail (full) and the composition of each detail level, providing useful transparency about output verbosity. No side effects are mentioned, which is acceptable for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The main action and default behavior are front-loaded, and the detail-level guidance is compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-get tool with full schema coverage and a clear output description, this is nearly complete. Medium detail is only described as 'compact summary,' but the schema provides the exact semantics, so the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by tying detail levels to storyline-specific content (full includes brief, strategy, line items, status; short returns id,title,status), enriching the schema's generic detail descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a single storyline by ID' and enumerates the included state fields (brief, strategy, line items, status), making it distinct from sibling list/get_strategy tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is clear: retrieving one storyline by ID. It provides guidance on detail level choices (full/medium/short) but does not explicitly name alternative tools like storyline_list or storyline_get_strategy, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals the ordering (isFavorite desc, then usageCount desc) and precisely defines the returned fields for each detail level. It doesn't mention pagination or side effects, but the read-only nature is implicit and the ordering/detail disclosures go beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the primary purpose. Each sentence adds distinct information: purpose, detail variations, filtering, and ordering. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description explains return values via detail levels. It covers filtering and ordering. The main gap is no mention of pagination or result limits, which might be relevant for a list operation, but the tool is simple enough that this is not a significant omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning to the detail parameter by spelling out exactly what short/medium/full include, and gives tangible category examples ('hook', 'cta', 'thread'). This goes beyond the schema's enum labels.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'List the brand's saved content templates,' a specific verb+resource phrasing that clearly distinguishes this as a read-only listing tool. It differentiates from sibling template tools (create/update/delete/extract/pick) by focusing on listing and enumerating the detail levels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it explains how to filter by category and what the detail parameter controls. It does not explicitly state when to prefer this over alternatives, but the list-oriented nature and the provided filtering guidance make appropriate usage evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the key behavioral nuance that only supplied fields are changed, which prevents accidental clearing of unspecified fields, and clarifies the favorite toggle semantics. It doesn't discuss error handling or return values, but for a simple update operation this provides sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences front-load the purpose and then deliver the partial-update behavior and favorite toggle instruction. Every word earns its place, no redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema and the simplicity of an update operation, the description covers the essential partial-update behavior. However, with no output schema, it doesn't mention what the tool returns (updated object, success message, etc.), leaving a minor gap for agents expecting a specific response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all 9 parameters with 100% coverage, setting a baseline of 3. The description adds critical meaning that omitted fields remain unchanged, which is not apparent from the schema alone. This partial-update clarification enhances parameter understanding beyond the raw field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('existing content template'), clearly distinguishing it from sibling template_create, template_delete, template_list, template_extract, and template_pick operations. It explicitly states the function is for updating, not creating or deleting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context that this tool modifies an existing template and that all fields are optional, implying partial updates. However, it does not explicitly mention when not to use it or name alternatives, so it lacks the explicit 'when/when-not' guidance that would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that results are returned as-is/unsummarized, describes the output shape (answer plus sources with title, URL, description), and advises passing results straight through. This is solid behavioral coverage, though it omits potential errors or rate-limit considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly verbose but every sentence contributes—examples, sibling distinction, output format, and pass-through instruction. It is front-loaded with the primary purpose and avoids unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with no output schema, the description adequately covers return value structure, usage context, and behavioral guidance. No critical information is missing given the tool's simplicity and schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well documented. The description adds example queries for the 'prompt' parameter but doesn't elaborate on 'brandId'. This meets the baseline for schema-heavy tools without adding significant extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs a live web search and returns a text answer with sources. Includes specific example queries and explicitly distinguishes from the sibling search_web_images, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use context ('for questions like...') and directly contrasts with search_web_images ('which only returns images'), giving the agent clear guidance on when to select this tool over the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does an excellent job. It discloses the return object (checkoutUrl, sessionId, tier, interval, amountUsd), the ongoing effect (credits refill User.credits each billing period), and a payment limitation (Link virtual card covers first invoice only, renewals need durable payment). This is rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose. The second sentence references the return shape, and the third adds a practical human/payment caveat. No filler; every sentence carries meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a subscription checkout tool, the description is complete: it explains what it creates, what it returns, how credits recur, and a payment method caveat. Even without an output schema, the return fields are enumerated. No critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of the parameters with clear enum descriptions for tier and interval. The description adds no new syntax or format details beyond mentioning the return fields. Baseline 3 is appropriate because the schema already documents parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Create a Stripe Checkout session for a PostKing subscription.' It also distinguishes itself from sibling billing tools (billing_topup, billing_wallet) by focusing specifically on subscription checkout, not wallet top-ups or tier listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'The subscription Checkout is best completed by a human,' which guides the agent to potentially hand off to a human. It does not explicitly name alternative tools like billing_topup, but the context is sufficiently clear. Lacks explicit 'when not to use' guidance, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It discloses the LLM extraction pipeline behavior, criteria for skipping (duplicates, too vague, previously rejected), the return format { addedCount, skippedCount, added, skipped }, and instructs the user to review skipped reasons. This is rich behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it starts with the core purpose, then gives format constraints, explains the underlying pipeline, details the return value, and ends with actionable advice. Every sentence adds value and there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no annotations and no output schema, the description is remarkably complete. It explains the tool's behavior, input format, output structure, and practical guidance on interpreting results. The only unaddressed aspect (brandId default) is covered by the input schema, so the description is fully sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both text and brandId, so baseline is 3. The description reinforces text usage (plain prose, ≤8000 chars) but doesn't add significant new meaning beyond the schema. brandId is not mentioned in description, but schema handles it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Capture brand truths from plain natural-language text.' It uses a specific verb (capture/create) and resource (brand truths), and distinguishes itself from sibling tools like brand_truth_get, brand_truth_update, and brand_truth_list by focusing on extraction from prose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on how to use the tool: write plain natural-language prose, don't pre-classify or format, and the pipeline will handle extraction. It implicitly differentiates from update/get/list siblings by focusing on creation from free text, but it doesn't explicitly state exclusions or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It excellently discloses async behavior, credit cost (~20 credits), return shape ({ operationId, status }), polling target (get_job), and typical duration (~2–5 min). This goes well beyond the minimal 'generate' verb and gives the agent a precise mental model of the tool's side effects and flow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the async nature and purpose, and directly follows with the essential operational details (credits, return shape, polling, time). Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async generation tool with a single optional parameter and no output schema, the description is complete: it explains the expected return value, the polling mechanism, the time estimate, and the cost. The combination of purpose, behavior, and operational guidance fully equips an agent to invoke and follow up on this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the only parameter (brandId) with a clear description, and schema description coverage is 100%. The tool description adds no additional parameter semantics beyond what the schema already provides, justifying the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Generate the competitive landscape overview'. It also distinguishes this from sibling tools like competitor_get_overview by explicitly marking it as async and returning an operationId, which implies it initiates a background job rather than retrieving an existing result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it's an async operation that requires polling get_job until completion. It doesn't explicitly name alternatives or exclusions (e.g., using competitor_get_overview for existing overviews), but the async pattern and polling instructions effectively guide the agent on when and how 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the brand is set as active, that a nextStep payload is returned, and that onboarding fails without a description. This gives the agent a clear understanding of side effects and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the step and path, and packed with essential flow information. No redundant wording; every clause contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return value (nextStep payload) and provides the immediate next action. It covers the prerequisite (description) and failure condition, making it complete for this multi-step onboarding tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds crucial context: description is effectively mandatory regardless of schema's conditional requirement, and website is not used in the manual path. It also clarifies the name/description are the user-supplied inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it creates a new brand from user-supplied name/description, sets it active, and returns a nextStep payload. Distinguishes itself as STEP 1 of manual onboarding, differentiating from sibling tools like set_brand_mediums or onboard_brand.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly positions itself as STEP 1 of the manual onboarding path, implying a website-crawl alternative exists. It provides direct next-step instructions to call set_brand_mediums after the user answers, but doesn't explicitly name the alternative tool or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the operation is permanent, explains the repointing behavior for draft deletion, specifies server rejection scenarios, and notes that rejection reasons are returned as-is. This gives sufficient transparency for a 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—three sentences, each earning its place. The purpose is front-loaded, followed by constraints and the confirm flag requirement. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema and annotations, the description is complete for correct invocation: it covers the operation's destructiveness, allowed/disallowed cases, error response behavior, and the confirm prerequisite. The schema already covers the remaining parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters, so the baseline is 3. The description adds the contextual nuance that deleting the current draft repoints to the newest remaining version, but it does not add parameter-level details beyond what the schema already provides (e.g., versionId source, confirm requirement).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Permanently delete a historical side-page version,' which clearly identifies the verb (delete), resource (side-page version), and scope (historical). It distinguishes from sibling tools like delete_side_page (delete whole page) and delete_lp_version (landing page version) by explicitly targeting side-page versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear constraints on when deletion is permitted: deleting the current draft is allowed, while published/live versions and the only remaining version are rejected. This gives when-not guidance, but it does not explicitly mention alternative tools (e.g., restore_side_page_version or delete_side_page) for different deletion needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses key behaviors: async generation requiring polling, return of articleId and operationId, and the exact follow-up calls. It doesn't mention failure modes or side effects like credit consumption, but the critical async behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence is packed with actionable information: prerequisites, async behavior, follow-up tools, and publication steps. No fluff or repetition; it's concise and clearly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the full lifecycle for a complex async tool: prerequisites, input sources, output identifiers, polling, retrieval, editing, and publishing. It's complete enough even without an output schema, and the sibling references orient the agent within the broader toolset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 92%, so the baseline is 3. The description adds meaningful value beyond the schema by explaining the provenance of publicationId and voiceProfileId, and reinforcing the async flow. It doesn't just restate parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Generate a full AI blog article,' using a specific verb and resource. It clearly distinguishes itself from sibling tools like generate_post (social posts) and generate_text by focusing on blog articles with a publicationId requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: requires publicationId from list_blogs or create_publication, voiceProfileId from list_voices, and explains the async workflow with next steps (poll status, retrieve, edit, publish). It doesn't explicitly say when not to use this tool versus alternatives, but gives strong contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by explaining the two-step process, async nature, return values, and polling with get_job until terminal states. It does not cover side effects like permissions or idempotency, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: purpose, step sequence, return format, polling instructions, and an alternative. It is compact yet information-dense with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's async, multi-step nature and absence of an output schema, the description thoroughly covers the return shape, polling procedure, and error states. It is complete enough for an agent to invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific detail ('with the given slug') but otherwise relies on the schema, which already covers all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create and AI-generate a new landing page for the brand.' It uses a specific verb and resource, and explicitly distinguishes from the sibling vibe_edit_landing_page by noting that targeted edits should use that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool (creating a new page) and provides an alternative for a different case: 'For targeted edits to an existing page, prefer vibe_edit_landing_page.' This directly guides tool selection versus a key sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains the asynchronous behavior: waits a short grace window, returns a 'generating' status if still running, and does not block. It also discloses that credits are deducted, which is a critical side effect for an agent to know before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: two sentences that first state the purpose, then provide essential behavioral details and follow-up instructions. Every sentence adds value, and there is no redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a tool with no required parameters and no output schema. It explains the asynchronous return behavior, the need to later call list_themes, and the credit deduction. This gives an agent enough context to use the tool correctly and handle the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters have descriptions in the schema. The tool description itself does not add further elaboration on parameter semantics. Since the schema already does the heavy lifting, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate new content themes using AI.' This is a specific verb+resource combination that distinguishes it from related sibling tools like list_themes, edit_theme, and delete_theme. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage: it generates themes and then instructs to 'call list_themes a few seconds later to retrieve the new themes.' This gives a sequential workflow. However, it does not explicitly mention alternatives or when not to use this tool, though the follow-up reference to list_themes implies the intended flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It fully discloses the output shape for each detail level, notes that 'persona' may be null, and warns about the prerequisite that audience data may not exist. It could mention explicit read-only behavior, but 'Fetch' implies it, and the level detail is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact, well-organized paragraph that front-loads the core purpose, then efficiently explains levels, the persona field, and a critical prerequisite. Every sentence earns its place; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must fully explain return values. It does this thoroughly for all three detail levels, clarifies the nullable persona, and gives an actionable precondition. For a simple get tool with two documented parameters, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by enumerating exactly what each detail level includes (e.g., 'short = compact summary (name + primaryRoles + top painPoints + persona.role)'), which enriches the enum meaning far beyond the schema's generic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Fetch the brand's audience intelligence / ICP'. It clearly differentiates from sibling tools like edit_audience and preview_audience_edit by being the retrieval tool, and it names the exact data being fetched.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (when audience intelligence/ICP is needed) and provides an explicit alternative for when data is missing ('If the brand has no audience data yet, run website/audience analysis (onboarding) first'). It also explains the detail level options, helping the agent choose the right verbosity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full behavioral disclosure burden. It clearly declares the read-only nature and includes an important exclusion (Reddit). It could add more detail about return format or error behavior, but for a simple getter, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no filler. The main purpose is front-loaded, and the Reddit clarification is presented as a necessary note. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-output-schema read tool, the description is complete. It states the purpose, read-only safety, and the crucial Reddit distinction, fully covering the context an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for parameters is 100%, and the only parameter brandId is fully documented in the schema with 'defaults to active brand'. The description adds no additional parameter-level detail, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('publishing platforms (mediums) a brand posts to'), making the tool's function immediately clear. It also distinguishes itself from the sibling tool set_brand_mediums by explicitly labeling itself as the read-only counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states exactly when to use this tool (reading a brand's platforms) and contrasts it with set_brand_mediums. The note about Reddit being a separate module and pointing to reddit_* tools provides clear alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly labels the operation as 'Read' and enumerates the content areas covered (content/structure/engagement/visual-strategy, secrets, etc.), which provides useful context beyond simple 'read' semantics. However, it does not disclose potential access requirements or return behavior in detail, though this is less critical for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description comprises two sentences, with the first defining the tool's purpose and scope, and the second providing explicit usage guidance. It avoids redundancy and every sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two optional parameters, no output schema, and no annotations, the description is sufficiently complete: it explains what data is returned (the rules and their categories), where it comes from (dashboard settings), and when to use it (before setting rules). This covers all necessary context for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both brandId and platform having full descriptions. The tool description does not add parameter-level semantics; it merely references per-platform rules. Per the baseline rule for high schema coverage, a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Read a brand's per-platform social media content rules.' It also distinguishes itself from sibling set_social_media_rules by naming that tool and clarifying its read-only nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Call this BEFORE set_social_media_rules so you only change the fields you intend to.' This gives a clear ordering relative to an alternative, which satisfies the dimension's requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It states 'No authentication required' and 'safe to call,' which are important transparency cues. It also indicates the tool checks both API health and local auth state, setting expectations for output. It does not mention potential side effects (none expected) or rate limits, but for a health check it is adequately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences that front-load the primary purpose. The first sentence states the verb and resource; the second adds safety, timing, and expected outcome. Every phrase earns its place, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 0-parameter tool with no output schema, the description is complete. It covers what the tool does, when to call it, safety characteristics, and what to look for in the result. Nothing significant is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema coverage is 100% (empty object). The baseline for 0 parameters is 4, and the description adds no parameter-related information because none is needed. This is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Check' and a clear resource: 'PostKing API health and local auth state.' It explicitly mentions what to expect: whether you're logged in and what to do next. This distinguishes it from sibling tools like login_start, whoami, and logout, which focus on different aspects of authentication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'safe to call first thing in a session to see whether you're logged in and what to do next.' It indicates when to use the tool but does not explicitly name alternatives or exclusions. The guidance is sufficient for a health-check tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly explains that the item is soft-deleted (isActive=false), disappears from knowledge_list, and cannot be reversed via the API. This is rich, transparent detail beyond what the schema or name provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the verb 'soft-delete', and each sentence provides a necessary piece of information: what it does, the effect, and irreversibility. There is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 params, no output schema), the description is complete. It explains the primary action, the observable effect (isActive=false and removal from list), and an important constraint (irreversibility). No additional information is needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters with meaningful descriptions (itemId and brandId, including brandId's default behavior). The description adds no additional parameter semantics beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'soft-delete' and the resource 'knowledge-base item', and distinguishes it from sibling knowledge_* tools by specifying the effect (isActive=false, no longer appears in knowledge_list). It also notes irreversibility, which reinforces its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on the tool's behavior and consequences: it's a soft-delete, deactivates the item, and is irreversible. While it doesn't explicitly name alternatives, the context is sufficient for an agent to decide when 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It transparently explains that the tool returns a URL+code, that login_complete will wait by polling, and that the agent should not wait for user confirmation. This is valuable context for correct sequencing. It could add fallback behavior (e.g., if user cancels or the code expires), but for a simple flow it is quite transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences. The first sentence states purpose and output; the second contains the critical sequencing instruction, clearly flagged with 'IMPORTANT.' Every word earns its place, and the structure front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description is fully self-contained. It covers what the tool does, what it returns, and the exact follow-up action (call login_complete). The agent has enough context to invoke the tool correctly and handle the next steps without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides no parameter details. According to the rubric, a 0-parameter tool gets a baseline of 4. The description appropriately focuses on the tool's output and the immediate next action rather than parameter intricacies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Start the PostKing login flow.' It specifies the output ('Returns a URL and short code') and distinguishes itself from the sibling tool login_complete by focusing on the initiation step rather than the completion step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit step-by-step guidance: show the URL+code to the user, then immediately call login_complete, explaining that it polls in the background. This is clear when-to-use context. However, it does not explicitly mention when not to use the tool (e.g., if already logged in) or compare it to other auth-related tools like whoami/logout.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains pickArgs requirements and mentions the editInVisualEditor result field, but it does not disclose whether this is a mutating action that overwrites an existing visual, what permissions or brand context are required beyond 'active brand is set', or error behavior. This is a partial but not complete behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all information-dense and front-loaded: the first states the core purpose, the second details exact usage mechanics, and the third notes a useful return field. Every sentence earns its place with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential input semantics and one return field, but since there is no output schema and no annotations, it could go further by stating the full response shape or whether the call replaces/updates the existing post visual. It is close to complete for correct invocation, though not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 100%, the description adds significant meaning beyond the bare schema descriptions: variant is a 1-based index, kind is required for card/quote templates, and parameters must come directly from generate_post_visual_options pickArgs. This is exactly the kind of semantic clarification agents need.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Select a visual for a post on a given platform.' It clearly differentiates from sibling tools like regenerate_post_visual and clear_post_visual by referencing pickArgs from generate_post_visual_options and mentioning the editInVisualEditor URL field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage rules: use pickArgs VERBATIM, pass kind+style+variant together for card/quote templates, pass assetId or slot for library/smart/stock assets, and do not invent style names. This gives clear when/how guidance and implicitly distinguishes from alternative visual tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses side effects: it gates brief generation, kicks off an async job, returns an operationId, and instructs polling get_job with specific terminal states. It also notes timing (~2-5 min). This is thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: action, flow position, timing, and return/polling behavior. Front-loaded with the primary action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description explains the return shape and async workflow completely. It covers prerequisites (via flow position) and error handling via polling states, making it sufficient for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both params. The description adds little beyond schema, though it reinforces that clusterId comes from seo_list_clusters (already in schema). Baseline 3 applies because schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Approve a single cluster,' which is a specific verb and resource that clearly states the action. It distinguishes from siblings by emphasizing 'single' (vs. bulk) and clarifying its role as a gate for brief generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit flow position: 'after seo_generate_clusters + seo_list_clusters, before seo_generate_roadmap / brief review.' This tells the agent when to call it. It does not explicitly name alternatives like seo_bulk_approve_clusters, but the 'single cluster' wording implies the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses key behavioral traits: it fires an async seo_brief_generate Operation per cluster, only on approved clusters, typical duration, response shape, and polling instructions. This is comprehensive and goes beyond bare operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses every sentence for essential information: async behavior, timing, response format, and polling steps. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema and annotations, the description is remarkably complete. It explains the asynchronous workflow, expected duration, response structure, and how to check status via get_job, leaving no critical gaps for an agent to invoke and follow up.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-documented. The description does not add substantial new parameter semantics beyond the schema; it only restates that clusterIds identify clusters to approve, which is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'bulk-approve' and resource 'clusters', clearly distinguishing it from siblings like seo_approve_cluster and seo_bulk_reject_clusters. It also states the operation is done 'in one call', providing clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context with 'Step 5b' and 'Recommended path when an agent wants to move multiple clusters forward.' It does not explicitly mention alternatives or when-not-to-use, but the intent is well conveyed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the default 'short' return shape, exactly what each detail level returns, and intentionally omitted fields (keywordsMeta, contentMix, briefAssignments) with a rationale. This is substantial behavioral insight 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: purpose first, then return-detail options, then filtering. It is well-structured and avoids redundancy while covering multiple detail levels and filters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description fully documents return shapes, filtering options, field omissions, and workflow next steps. It is complete for a 7-parameter list tool; the only minor omission (brandId behavior) is already covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value by explaining detail-level field sets, CSV filter semantics, and q search scope, which goes beyond the bare schema descriptions and helps the agent select appropriate parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List clusters' and explains the workflow purpose: 'so the agent can pick one (or several) to approve before brief and roadmap generation.' It clearly distinguishes this from sibling list tools by focusing on clusters and their approval status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool ('Step 5', before brief/roadmap generation) and provides guidance on detail levels, including when to avoid full detail ('use cluster IDs with approve/reject tools directly'). It does not explicitly name alternative list tools, but the workflow context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden. It discloses key behavioral traits: the operation is a soft-delete (reversible) and requires explicit confirmation via 'confirm: true'. However, it does not mention potential side effects or permission requirements, which is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff, front-loading the primary action and then providing critical instructions. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with full schema coverage and no output schema, the description covers purpose, confirmation requirement, and reversibility. It is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, so the baseline is 3. The description adds the operational context that 'confirm: true' is required to proceed, but the schema already states this constraint. No additional parameter meaning is provided beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Archive (soft-delete) a storyline' with a specific verb and resource. It distinguishes itself from sibling tools by explicitly noting it is a soft-delete and referencing storyline_restore for reversal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage instructions: 'Pass confirm: true to proceed' and identifies the alternative tool for reversing the operation ('Use storyline_restore to reverse this'). This gives clear when-to-use and how-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It discloses server-side base64 encoding, the truncation risk crossing the LLM→tool_call boundary, and states the return value (asset ID and URL). However, it doesn't mention auth requirements or error handling, so it's not a perfect 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses six sentences to convey necessary caveats and alternatives. Though slightly verbose, every sentence addresses a practical concern (truncation, chunked flow, exclusivity), so it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no annotations or output schema, the description covers the key decision (filePath vs fileBase64), references the chunked flow, and states the return. Other parameters are adequately described in the schema, and the description integrates well with sibling tools like list_assets and upload_asset_abort.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 88%, so the baseline is 3. The description adds significant semantic value by explaining why filePath is preferred over fileBase64 and enforcing the constraint 'Provide exactly one of filePath or fileBase64,' which goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Upload an asset to the brand library from a local file path or base64-encoded content' with a clear verb and resource. It also distinguishes itself from the chunked upload flow by explicitly naming upload_asset_begin/chunk/finish for large files, and implies contrast with import_asset_from_url.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to 'Prefer filePath for local files' and describes when fileBase64 is appropriate for 'remote/inline use.' It also clearly directs users to the chunked flow for large files over remote/HTTP transport, providing a concrete alternative with the sequence upload_asset_begin → upload_asset_chunk → upload_asset_finish.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with no annotations, the description discloses key behavioral traits: it initiates a chunked upload, returns an uploadId, and that ID expires after 10 minutes of inactivity. It also explains the underlying reason (LLM→tool_call boundary truncation). It doesn't cover permission requirements or side effects, but the session semantics are well conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but perfectly scoped: three sentences covering purpose, when-to-use, the full flow, the return value, and the expiry. Every sentence adds unique value, front-loaded with the most critical information, and avoids fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-step operation with several sibling tools, the description is remarkably complete. It names the sibling steps, explains the advantage over upload_asset, notes the return value (uploadId) and its lifecycle, and sets expectations for the flow. No output schema exists, so the description's note about returning uploadId fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (88%), so the schema already documents most parameters (fileName, sha256, fileSize, etc.). The description adds no additional parameter-level detail beyond naming fileName implicitly and implying the upload flow. It meets the baseline for high schema coverage but doesn't elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb+resource ('Start a chunked asset upload') and immediately distinguishes from siblings: 'Use this instead of upload_asset's fileBase64 param for large files'. It clearly positions this as the first step in the chunked upload flow, differentiating from upload_asset_chunk and upload_asset_finish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool instead of upload_asset (large files over remote/HTTP transport where base64 might truncate), and provides the exact sequence: upload_asset_begin → upload_asset_chunk → upload_asset_finish. This gives the agent clear decision criteria and workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that rendered HTML appears only at full, that medium/full include currentVersionId and publishedVersionId, and that a mismatch indicates unpublished draft edits. This reveals the conditional output behavior clearly. It does not explicitly state read-only, but 'view' implies it, and no side effects are claimed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then compactly enumerates the detail-level behaviors and the version mismatch semantics. Every sentence adds value, and there is no filler. The length is appropriate given the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read/view tool with no output schema and no annotations, the description is remarkably complete. It explains the precise fields returned for each detail level, the meaning of the version IDs, and the recommended use case. This is sufficient for an agent to select and invoke the tool correctly without additional guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already covers all three parameters (100% coverage), the description adds significant meaning to the 'detail' parameter by specifying exactly what each value returns (rendered HTML and overrides vs. summary and overrideSectionKeys vs. id/slug/name/type/isPublished). This goes beyond the generic verbosity description in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'View a side page including sections and rendered HTML', a specific verb+resource that clearly states the tool's function. It further differentiates from siblings like list_side_pages and view_side_page_version by describing the detail-level variations and the intended use of reading a section's typed shape before editing with set_side_page_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use full detail ('use this to read a section's typed shape before editing it with set_side_page_section') and explains the trade-offs of each detail level. While it does not explicitly contrast with view_side_page_version or other siblings, the context and use-case are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on full transparency responsibility and succeeds. It discloses synchronous execution, auto-generated slugs, optional side-page creation, and an exhaustive report structure including truncation and extractability. It even describes the non-throwing refusal behavior for client-rendered app shells and instructs the agent to relay reasons and suggest alternatives, exceeding typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded, starting with the core purpose and then systematically covering inputs, return values, and error handling. It includes a concrete example, which aids comprehension. However, it is a single long paragraph that could benefit from bullet points or shorter sentences to improve scannability, though no content is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because there is no output schema, the description must fully document return values, which it does in remarkable detail: the report object with all fields, the error result, and the recommended user follow-up. It also covers all parameter interactions and failure modes, making it a self-contained reference for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% parameter coverage, but the description adds valuable semantics: it explains that html and url are mutually exclusive, that the slug is always auto-generated, and how convertExistingSlug overwrites existing content. These are not inferable from the schema alone, enriching the agent's understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'import an existing landing page from pasted HTML or a live URL' and even names the operation 'import_landing_page_html'. It distinguishes from siblings like generate_landing_page by emphasizing 'Bring-your-own-HTML' and synchronous behavior, making the tool's unique role evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit in-tool usage guidance: 'Pass exactly one of html or url' and explains when to use convertExistingSlug versus creating a new page. It also advises on the not_extractable error, suggesting static HTML as an alternative. However, it never explicitly names sibling tools as alternatives (e.g., generate_landing_page) when no existing HTML is available, so the when-not-to-use context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses a key behavioral limitation (may omit a just-started operation) and describes the output verbosity levels for the detail parameter. However, it does not explicitly state read-only nature or any side effects, though 'list' implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds value. The description is front-loaded with the most important usage distinction (get_job vs list), then explains filtering, polling, and detail levels. It is slightly long but densely packed with actionable information, with no redundant verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the essential aspects: what is listed, how to filter, how to get more detail, and when to use an alternative. It omits explicit mention of the limit parameter and pagination behavior, but the 'most recent ops' phrasing and schema field imply a default-limited list. This is adequate for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the detail parameter with a rich description (75% coverage), but the description adds meaningful shorthand semantics: 'short=id+kind+state, medium=6 key fields, full=raw'. It also explains the status filter's practical use. This goes beyond schema, though limit and brandId are left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists background jobs for the active brand, using the specific verb 'List'. It immediately distinguishes itself from get_job by directing users to call get_job for a specific operation's status, which makes the tool's scope unambiguous and differentiates it from the sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided on when to use this tool vs. alternatives: 'To check a SPECIFIC operation's status, call get_job with its operationId' and 'Use get_job with an operationId to poll a specific job'. It also explains filtering via status='pending' and 'completed', covering both selection and exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully discloses behavior: it returns only most recent ops, may omit just-started ones, and clarifies the state values and detail param effects. It doesn't mention ordering or pagination details, but the caveat about omitted operations is crucial and well stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Six sentences, but each contains useful information. The get_job guidance appears twice (first sentence and later), which is slightly redundant, but the front-loaded caveat and formatted detail map are efficient. Not the most compact, but earned length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description explains the operation object fields (id, kind, state, progress, result, errors) and per-detail-level contents. It also explains filters, brand scoping, and the relationship to get_job, covering all essential usage aspects for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 80% of parameters with descriptions, so baseline is 3. The description enhances this by mapping detail levels to concrete fields (short=id+kind+state, medium=adds scopeId+progress+timestamps, full=raw including result) and giving example kind values. This adds meaning beyond the schema's generic wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List recent Operations (the newer async-op system) for the active brand,' giving a specific verb, resource, and scope. It also distinguishes itself from get_job by calling it 'newer' and listing sibling-style ops, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use get_job with an operationId for a specific operation's status, and warns this list may omit a just-started one. Also provides filters for kind and state, giving clear context on when to use this versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, this description carries the full burden and exceeds it: it states the operation 'only changes the DRAFT', explains it 'moves currentVersionId forward to a new version copied from the target', and clarifies 'forward history is never deleted' and the live page is unchanged until publishing. This fully discloses the mutation and permanence characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentence description front-loads the purpose in the first sentence, then delivers workflow and side-effect details in compact, high-signal sentences. No filler or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description thoroughly covers the operation, prerequisites, and post-conditions. The only notable gap is the lack of any indication of return value or error behavior; without an output schema this could be helpful but is not blocking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already described. The description adds value by pointing users to list_side_page_versions as the source for versionId and by defining restore semantics (copying target into a new version), reinforcing the meaning beyond the schema's basic field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb 'Restore' and resource 'a side page's draft to a prior version,' clearly stating the tool's exact effect. It differentiates from sibling tools like list_side_page_versions and delete_side_page_version by focusing on draft restoration and explaining that forward history is never deleted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It instructs to 'Find valid version IDs via list_side_page_versions' and notes the live page is unaffected until 'set_side_page_state({ published: true })', providing a clear retrieval/publish workflow. It lacks an explicit statement of when not to use this tool vs delete_side_page_version, but the behavioral distinction is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it delivers with rich behavioral detail: auto-firing side effects, typical timing (3–8 min per article), async polling expectations with specific states, and a re-submission warning. It also discloses the response structure, making the tool's behavior fully predictable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and every sentence contributes actionable information, but it is a dense single paragraph that interleaves warnings, timing, and response format. Slight restructuring into sections would improve readability, though it remains appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the asynchronous and stateful nature of this tool, the description covers all critical aspects: side effect (generation), timing, required polling with get_job, handling of in-progress briefs, error states, and the exact response shape. No output schema exists, so this description fully compensates and provides complete operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description only re-states briefIds (array, max 200) and does not add meaning beyond the schema's built-in descriptions for brandId and generateHeroImage. This meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: approves one or more SeoBriefs and auto-fires L4 article/comparison generation. It distinguishes from the sibling tool seo_write_article by explicitly warning not to call seo_write_article after this.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance, including that this tool triggers generation immediately and that seo_write_article should not be called afterwards. It also instructs on polling with get_job and how to handle briefs already in 'writing' status, preventing duplicate submissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and excels: it discloses synchronous execution, return shape ({ updated, skipped, errors, total, results: [...] }), the skip behavior for Webflow-synced blogs and reason ('CTA edits don't push back to Webflow'), re-run safety (`overwriteExisting=false`), and limitations (keyword-only matcher, planned enhancement). This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely packed with pertinent information, well-structured with em-dashes and semicolons. It front-loads the core purpose and then covers defaults, return value, cap, and future plans. Every sentence adds value, though it could be more concise by trimming the future enhancement note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully covers what the agent needs to know: when to run, what it does, side effects, return shape, parameter semantics, batch limits, and edge-case skips. It even notes the synchronous nature so no polling is needed. This is complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining the 'all' literal for blogIds, the 50-blog cap and batching, and the meaning of `overwriteExisting` and `skipWebflowSynced` in context (safe re-run, why skipping Webflow). This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with specific verb and resource: 'Auto-suggests a published side-page CTA for each blog article in the batch' and writes to BlogArticle.sidePageInfo. It also specifies the matching criteria (keywords: cluster + tags + title) and the exact fields written, distinguishing it from other SEO or side-page tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'runs AFTER blog articles are published,' providing a temporal when-to-use. It also gives practical batching guidance ('Hard cap of 50 blogs per call... batch your blogIds arrays in groups of 50') and explains safe re-running via defaults. However, it does not explicitly mention when not to use or alternatives, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses critical side effects: 'Approving via this tool fires L4 article/comparison generation immediately and returns { brief, operationId }.' It also highlights the structured refinement constraint and indicates the canonical approval path. However, it does not describe what happens on 'rejected' status or what a non-approval edit returns, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. Each sentence adds value: the constraint about no free-text instructions, briefData/status usage, the side effect of approval, and the typical refinement loop. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description provides a strong workflow context: the refinement loop, the approval alternative, and the return shape for approval. However, it does not specify the return value for simple edits, nor does it mention conditional param restrictions like generateHeroImage only being valid for article-type briefs (though the schema covers that). Overall, it is nearly complete but leaves some path-specific gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains briefData as 'the full replacement JSON for the brief outline — H2s, FAQs, keyword targets, etc.' and clarifies the role of status and the refinement loop. This extra semantic value raises it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Edit an SeoBrief before approval,' which clearly states the action and resource. It distinguishes itself from the sibling seo_approve_briefs by explicitly saying 'prefer seo_approve_briefs for the canonical approval step,' making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: it says the inner route does not accept free-text 'instructions' and provides a typical refinement loop (seo_get_brief → mutate → seo_edit_brief → seo_approve_briefs). It also names an alternative tool for approval, which helps an agent decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It transparently discloses the default return format (short detail) and explains the meaning of each detail level ('short', 'medium', 'full'). It does not explicitly confirm side-effect-free read behavior, but for a gap-analysis tool this is reasonably safe to infer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences. The first states the core purpose, and the second explains the detail parameter without wasted words. Ideal length and front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only 2 optional parameters, no output schema, and no annotations. The description fully covers the tool's behavior, return variants, and defaults. There is no obvious missing information for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the schema. While the schema documents the detail enum as 'verbosity', the description clarifies exactly what each value returns (e.g., 'medium' gives searchVolume, difficulty, competitorDomains), which is essential for choosing the right level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb and resource: 'Identify content gaps'—topics competitors cover but the brand doesn't. This directly distinguishes it from sibling tools like seo_competitor or competitor_analyze, which focus on competitor data rather than gap analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on what the tool does and how to control output verbosity via the detail parameter. However, it does not explicitly mention when to use this tool over alternatives or exclusions, so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses async processing, expected duration (~2–5 min), the return payload, and the synchronous exception for comparison-type briefs. Also clarifies that freeform generates actual section-level content and specifies slug semantics. This is strong coverage of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, bulleted modes, and a closing clarification. Every sentence adds useful information without fluff. Appropriate length for the tool's complexity, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex async creation tool with no output schema, the description covers return values, polling instructions, error states, modes, and the SEO linkage benefit. It also specifies the parent slug requirement. Minimal gaps remain, and any missing lifecycle details are likely covered by sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds significant value by organizing parameters into usage modes (freeform vs brief), explaining which optional params belong to each mode, and clarifying that comparison-type briefs require a persisted briefId. It also reinforces key parameter relationships (key+prompt vs key+brief) beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it generates a side page for a landing page, with optional SEO cluster linkage. Distinct from generic side page generation by emphasizing cluster-context queries, keyword inheritance, and GEO authority. Verb+resource+scope is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides mode-specific parameter usage (freeform vs brief) and async behavior, including when to poll get_job and when comparison briefs run synchronously. Does not explicitly contrast with generic generate_side_page or other alternatives, but the SEO context implies its niche.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it discloses default return detail, exact fields per detail level, server-side filtering, hasTag OR-match semantics, includeDeleted default exclusion, and cursor pagination. This gives the agent a complete behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient, with each sentence adding functional value: purpose, detail levels, filter list, hasTag semantics, and pagination. It could be better structured with bullet points, but there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity list tool with no output schema and no annotations, this description covers purpose, output shape per detail level, filters, hasTag behavior, and pagination sufficiently. An agent can correctly select and invoke the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 95%, so the baseline is 3. The description adds meaningful context by clarifying hasTag as a CSV OR-match with geo-tagging examples, explaining detail verbosity values, and describing cursor-based paging beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' targeting 'generated keywords for the brand', clearly defining the tool's scope. It also distinguishes itself by specifying default return fields and detail levels, making it unambiguous among sibling SEO tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the tool is 'useful for auditing between steps' and provides guidance on detail levels and pagination. It also advises calling a get/view tool for zooming into an item, but does not explicitly contrast with the sibling seo_list_keyword_ids tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It covers async execution (~1–2 min), credit usage (unless dryRun), idempotent skipping of already-tagged keywords, retag and dryRun semantics, the return shape {operationId, status}, job result fields (tagCounts, ambiguousKeywords, costUsd), and polling via get_job. This is comprehensive and goes far beyond a basic 'classifies and writes tags' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but each sentence contributes useful information: the tag vocabulary, async timing, credit usage, return and polling flow, job result fields, idempotency, dry-run option, and follow-up tools. It is front-loaded with the core purpose and then adds operational specifics without repeating schema content. Slightly streamlined, but no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description provides a complete operational picture. It specifies the immediate return {operationId, status}, the job result structure (tagCounts, ambiguousKeywords, costUsd), the polling mechanism via get_job, error states (failed/partially_failed/cancelled), and the follow-up tools. It also explains idempotency and dry-run semantics, making it sufficient 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (retag, dryRun, brandId) are already fully described in the schema (100% coverage), so the description doesn't need to reintroduce them. The description adds value by explaining how retag and dryRun alter behavior, e.g., 'pass retag:true to force re-classification' and 'dryRun:true to get the full classification breakdown WITHOUT writing any tags', which contextualizes the schema and gives practical guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Geo pivot Stage 1. Async — classifies every keyword's geographic intent and writes a `geo:*` tag into userTags.' This specifies the action (classifies and writes tags), the resource (keywords' geographic intent), and the output location (userTags), distinguishing it from sibling SEO tools like seo_categorize.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear workflow context: it's 'Stage 1' of a geo pivot, recommends using dryRun 'first to review tagCounts and ambiguousKeywords before committing', and explicitly names follow-up tools (seo_list_keywords or seo_list_keyword_ids with hasTag=...) for selecting tagged keywords. However, it doesn't explicitly state when not to use this tool or name alternative tools for geographic intent classification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: credit consumption ('Uses credits'), latency ('Typically takes ~3–8 min'), return value ('Returns an articleId'), and a critical trap (avoiding duplicate generation when status is 'writing'). This goes well beyond a basic description and helps the agent avoid costly mistakes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every clause serves a purpose: alternative path, status check, duration, preconditions, and return. It is front-loaded with the most critical warning. While slightly dense, it remains well-organized and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers nearly all necessary context: prerequisites, duration, cost, return type, and related tools. It even instructs on how to handle edge cases (status 'writing', 'drafted', 'pending_review'). This is comprehensive for a complex workflow tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so most parameters have descriptions. The tool description adds context by tying roadmapItemId to the brief status, but it doesn't elaborate on 'count' or 'brandId' beyond what the schema already indicates. Overall, the description adds moderate value but relies on the schema for parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Draft a full blog article for a roadmap item.' It also distinguishes itself as an 'ALTERNATIVE write path' compared to seo_approve_briefs, which auto-generates. This specific verb+resource combination separates it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance: 'only call this when a brief was NOT approved via seo_approve_briefs' and 'If the brief status is `writing`, poll... rather than calling this again.' It also lists preconditions and alternative workflows with specific sibling tool names, making it exceptionally actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It adds valuable context: 'Each call creates a new draft version,' and explains the server-side mapping of section keys. It doesn't mention error handling or side effects beyond versioning, but for a content edit tool this is adequate. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that front-loads the core action, then efficiently explains key concepts and an example. Every sentence contributes useful information—no filler or repetition of schema details. At ~90 words it is appropriately sized for a tool with this complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool handles 7 parameters with complex semantics (dot-paths, replaceSection, section mapping), and the description covers these well, including versioning implications and tool selection guidance. It doesn't describe the return value or failure modes, but with no output schema and rich input descriptions, the existing coverage is strong. A score of 4 reflects the small gaps while acknowledging overall completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description enriches semantics by explaining the 'bare content-section key' concept, dot-path syntax with an example, top-level root acceptance, and the version-creation side effect. This goes beyond what the schema's parameter descriptions provide, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Set one field on a landing page section', and clearly distinguishes the two modes of operation (single field via dot-path or whole section via replaceSection). It also differentiates from siblings by pointing to vibe_edit_landing_page for multi-change edits, and the section-key mapping details set it apart from other landing page tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to prefer an alternative: 'for many related changes across a page, prefer vibe_edit_landing_page instead.' It also provides contextual guidance on acceptable inputs (bare content-section keys, top-level roots) and example usage, making the tool's application clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden of behavioral disclosure. It details the valid section keys, the order of operations (order first, then visibility), independence of each operation, the exact result shape including partialFailure, and the condition for throwing. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but dense with necessary information. It front-loads the main purpose, then covers requirements, valid keys, execution order, and error semantics. Every sentence contributes, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity with 3 parameters and a nested object, but no output schema. The description compensates by explicitly describing the result shape and partial-failure behavior. It is nearly complete, except it does not enumerate which section keys are in the 'toggleable subset' for sectionVisibility, leaving that detail unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter is described, giving a baseline of 3. The description adds significant meaning beyond the schema: it clarifies the relationship between sectionOrder and sectionVisibility, the independent application of both, and the meaning of the result object. It stops short of enumerating the toggleable subset for sectionVisibility, which is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Reorder and/or toggle visibility') and clearly identifies the resource ('landing page's sections'). It distinguishes itself from sibling tools like set_landing_page_section (which likely edits a single section) by focusing on layout-level reordering and visibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage conditions: pass at least one of sectionOrder/sectionVisibility. It explains behavior when both are given and the partial-failure model. However, it does not explicitly name alternatives or contrast with other landing page editing tools, so it lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on the full burden. It discloses the default merge behavior, that arrays replace the old array, and that replace=true overwrites the entire ruleset. It doesn't cover every edge case (e.g., nested object merging, return value), but the key non-destructive vs. destructive behaviors are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, using three sentences to convey the purpose, the merge behavior, the replacement option, and a helpful tip. No redundancies or filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool, the description covers the essential behavior, valid platforms, and a read-before-update tip. It doesn't mention return values or error conditions, but with no output schema and a relatively simple operation, this is acceptable. The only major ambiguity is whether nested objects are deep-merged, which could be clearer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage for parameters, but the description adds value by explaining the practical implications: send only what you want to change and how array fields behave. It also clarifies the replace flag's effect beyond the schema's one-line description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Update) and the resource (a brand's social media content rules) with a specific scope (for ONE platform). This distinguishes it from the sibling get_social_media_rules tool by explicitly positioning it as the update counterpart and listing valid platforms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage context: merge vs. replace semantics, and the tip to call get_social_media_rules first to see current values. This gives the agent clear guidance on how to use the tool effectively and which sibling tool is complementary for reads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses output verbosity levels and field composition, and the act of listing implies read-only behavior. However, it does not mention pagination, ordering, or precisely define what 'raw' means for full detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main description is two concise sentences that front-load the purpose and use compact field notation. The schema carries necessary additional detail without unnecessary repetition, making the whole definition efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with two optional parameters and no output schema, the description adequately conveys scope and return shapes for three verbosity levels. It does not explicitly state whether the response is an array or a single object, nor mention pagination, but the tool name and sibling guidance cover enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by specifying exactly which fields are included at each detail level ('id,title,status' vs 'isLive, dates, promptSummary'), while the schema itself documents defaults and brandId behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List the brand's storylines (marketing plans)'. It clearly differentiates this listing operation from sibling tools like storyline_create, storyline_get, and storyline_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The schema's detail parameter explicitly instructs that lists default to 'short' and that to zoom into one item, the agent should call its get/view tool with detail='medium' or 'full'. This provides direct when-to-use vs. alternative guidance, going beyond generic context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it discloses that malformed CTA shapes are rejected by the server, external featured image URLs are auto-downloaded on publish, empty string removes the image, and that `cta`/`sidePageInfo` are mutually exclusive. It also warns against putting CTA markup in the content body.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but each sentence delivers practical value. It front-loads the core edit capability and then delves into CTA specifics with clear, structured guidance. Minor redundancy exists in the CTA explanation, but overall it is efficient given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter tool with nested objects, no output schema, and no annotations, the description covers all major behaviors, field interactions, and constraints. It thoroughly explains the two advanced CTA modes, status semantics, image handling, and server-side validation, giving an agent everything needed to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 73% of parameters with descriptions, but the description adds meaning beyond the schema: it explains the CTA object structure, how to clear it, the mutual exclusivity with sidePageInfo, and the behavior of featuredImageUrl. The first sentence also groups the many fields into coherent categories, making the tool's parameter space easier to digest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Edit' and clearly enumerates the editable resources (title, content, excerpt, SEO fields, status, author, category, images, CTA), making its purpose unambiguous. It naturally distinguishes itself from sibling tools like get_blog_article, schedule_blog_article, or publish_blog_article by focusing on modification rather than retrieval or scheduling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use specific features: 'Set status='published' to make it live' and the choice between `cta` for raw URLs and `sidePageInfo` for linking to existing side pages. It does not explicitly exclude alternatives, but the context is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses that 'it does NOT change anything by itself' and returns only an operationId. It also reveals the async nature (polling) and that vibe-edit sessions reside in a separate store from the generic job queue. This is rich behavioral context that fully informs the agent about side effects and operational expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized with numbered steps and inline flow annotations. Every sentence contributes to understanding the multi-step process, but the density of information makes it slightly heavier than strictly necessary. It is efficient for the complexity, though a bit over the ideal minimal size.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description masterfully covers the full lifecycle: returns operationId, how to poll, what to expect in the changes array, and how to proceed to apply and publish. It also handles edge cases like the separate store and sectionId requirements. The agent has everything needed to use this tool correctly without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the scope-sectionId dependency and lists example section keys, but these are already present in the input schema. It adds workflow context rather than new parameter-level semantics, so it doesn't elevate above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Use AI to propose an edit to a landing page based on natural-language instructions.' It also explicitly frames this as 'step 1 of a propose → review → apply flow', which distinguishes it from sibling tools like apply_vibe_edit and edit_landing_page. The verb, resource, and scope are all specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit step-by-step workflow: call this tool, poll get_vibe_edit_status (NOT get_job), review the changes array, call apply_vibe_edit, then publish_landing_page. It also clarifies when scope='section' requires sectionId. This goes beyond generic guidance by naming the exact alternative to avoid (get_job) and explaining the separate store, making the usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It reveals that this creates exactly one new version, does not publish, can be undone via restore_lp_version using a returned previousVersionId, and returns a structured stale_session error instead of applying in a stale session. These are critical side-effects and error conditions not otherwise conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact given its complexity: three sentences covering purpose, usage, and error handling. It is front-loaded with the primary action. However, the third sentence is quite long and dense, mixing stale_session handling with force=true and re-run advice, which takes extra parsing effort.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 8 parameters, no output schema, and no annotations, but the description covers the most vital aspects: the workflow (from vibe_edit_landing_page to publish), the undo mechanism, and the stale_session error path. It does not fully describe the success return payload (beyond previousVersionId) or other potential errors, but it addresses the most common and operationally critical behaviors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes above that by explaining the mutual exclusivity of all/indices/paths and how to source indices/paths from get_vibe_edit_status. It also clarifies the meaning of force=true in the stale_session context, adding value beyond the schema's individual parameter descriptions, though it does not elaborate on every parameter like name/description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and object: 'Applies a completed vibe edit... to the DRAFT as ONE new version.' It clearly distinguishes this from siblings by explicitly stating it does NOT publish (publish_landing_page) and can be undone (restore_lp_version), tying into the surrounding workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use instructions: 'Pass exactly one of: all=true, indices, or paths' and clarifies how to obtain those subsets. It also provides alternative actions for the stale_session error (re-run vibe_edit_landing_page or retry with force=true), and explicitly says to call publish_landing_page next, leaving no ambiguity about the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It states that the tool returns all packs with SKU, USD price, and credit amount, but does not explicitly declare read-only status or discuss error conditions. However, the verb 'List' and the workflow context strongly imply a non-mutating operation, and the return content is well specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose, return content, and usage flow. Every sentence adds value and there is no redundancy. The information is front-loaded, with the core purpose in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with no output schema, the description provides the essential information: what it lists, what fields are returned, and how to proceed. It fully equips the agent to use the tool in the intended workflow, including the connection to billing_topup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts no parameters, so the schema covers 100% of the parameter space. The description adds no parameter information, which is appropriate. The mention of packSku is for the downstream billing_topup call, not for this tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List available credit packs for one-off top-ups,' which is a specific verb+resource+scope statement. It clearly distinguishes from billing_topup (which performs the actual top-up) and billing_list_tiers (subscription tiers).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to call this tool first, then ask the user to choose a pack, and only afterward call billing_topup with the chosen packSku. This provides clear sequencing and names the alternative tool, leaving no ambiguity about when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that 'recent is the last ~10 usage rows' and that polling should continue 'until credits rise,' which gives useful behavioral context about how the returned data changes over time. However, it does not explicitly state that the operation is read-only or describe error scenarios, so it falls just short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the purpose. Each subsequent sentence adds critical usage guidance—when to poll and when not to poll. There is no fluff or repetition; every sentence earns its place. The structure is logical and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool with no annotations, this description is remarkably complete. It covers the purpose, the exact return shape, and the full polling semantics with clear conditions for use. It even explains the distinction between two top-up flows, which is critical for correct invocation. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty schema). Per the rubric, 0 parameters gives a baseline of 4. There is no parameter information to add, and the description correctly focuses on the return value and usage semantics instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Fetch the user's credit balance and recent usage entries,' which is a specific verb+resource statement. It also gives the exact return shape '{ credits, recent }' and differentiates itself from siblings by focusing on recent usage entries and the polling context for top-ups. This clearly distinguishes it from similar tools like get_credits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Poll this to confirm a top-up landed ONLY after a billing_topup CHECKOUT result... until credits rise.' It also gives a clear exclusion: 'Do NOT poll after a status:'paid' headless top-up.' It names the related tool (billing_topup) and provides precise conditions, making it an excellent usage guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It discloses the async nature, the return shape ({ operationId, status }), the need to poll get_job, and a typical duration of ~2–5 minutes, giving the agent a clear operational model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences cover async status, usage differentiation, and return/polling/ETA with no filler. The front-loaded 'Async.' immediately sets expectations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description specifies the return shape, polling behavior, and expected runtime, which is sufficient for a simple async trigger tool with two params. It leaves no critical ambiguity for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with brandCompetitorIds and brandId fully described in the input schema. The description adds no new parameter semantics beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Async. Trigger analysis for existing BrandCompetitor rows that are pending or failed,' naming a specific action, resource, and scope. It differentiates itself from sibling competitor_add by explicitly stating it is for retry rather than creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use competitor_add to create new rows; use this to retry failed ones,' providing clear when-to-use versus an alternative. It also instructs to poll get_job until completion, giving practical next steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the raw token is returned only once and never shown again, advises treating it like a password, and explains the scope options and default. This goes beyond the schema and gives critical safety information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and every sentence adds essential information—no filler. The warning about token visibility is concise but critical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking annotations and an output schema, the description covers the essential behavioral context for a create operation: the one-time token return and security admonition. With only two parameters and a simple schema, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters with 100% coverage, providing a baseline of 3. The description adds meaning by explaining the scope choices ('write' (default) or 'read') and implying what they control. It also mentions the token format, which clarifies the output context, though it doesn't add parameter syntax details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Create a new PostKing API key.' The verb 'create' and resource 'API key' are specific, and the scope options distinguish it from sibling tools like list_api_keys and revoke_api_key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 the tool—when a new API key needs to be created—and includes useful scope guidance (write/read). However, it does not explicitly name alternatives or exclusion criteria, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure burden. It clearly states the operation is permanent/destructive, specifies preconditions, and explains the failure mode (API refuses with explanation). This is exemplary transparency for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, followed by necessary conditions and guidance. Every sentence earns its place with no unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with 2 parameters and no output schema, the description covers the essential context: permanence, prerequisites, error behavior, and cleanup guidance. It is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not add parametric details, but the input schema already contains full descriptions for both brandId and publicationId (100% coverage). Baseline 3 is appropriate since the schema handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pair ('delete a blog publication') and clearly distinguishes this from sibling tools like delete_blog_article and delete_theme. It states the action is permanent, adding precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool is allowed (zero articles, no connected domain/external sync/publishing connections) and what to do otherwise (remove/disconnect first, e.g., delete_blog_article). This provides clear context and actionable alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully compensates by disclosing async execution, returned fields (`operationId`, `pollUrl`, `sidePageId`), sync fallback for comparison briefs, and polling error states. It also notes that freeform mode 'now writes real section-level content... not just metadata', adding meaningful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but every sentence serves a purpose: endpoint identity, return shape, mode selection, and polling behavior. It uses a structured 'Two body modes' list to remain scannable despite the complexity, with no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 11 parameters, async behavior, no output schema, and multiple generation modes, the description covers all critical aspects: return object, sync/async distinction, polling state values, section-level content generation, and field combinations. An agent has enough information to invoke and monitor the operation correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds important mode-based semantics: freeform uses `key`+`prompt` with optional fields, brief uses `key`+`brief` with optional `briefId`/`roadmapItemId`, and `sidePageType` defaults to 'landing' with comparison requiring a persisted briefId. This grouping helps the agent choose correct parameter combinations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The definition clearly states that the tool 'AI-generates a side page under a parent landing page' and identifies it as the generator endpoint 'POST /side-pages/generate', explicitly noting it is 'NOT a row creator'. This scope and differentiation from editable/row-manipulation tools is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage modes ('freeform' vs 'brief') with parameter bundles, and instructs the agent to poll `get_job` with `operationId` until terminal states. It explains when comparison-type briefs run synchronously, but does not name alternative sibling tools like `seo_generate_side_page` or `create_comparison_page`, so exclusions are only partially addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states async execution, the return format { operationId, status }, the need to poll get_job, auto-generation of description/tags when omitted, client-side JSON validation, and the typical 15-30s duration. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each carrying critical information: async nature, purpose, return/polling, and edge cases. It is front-loaded with 'Async.' to set expectations and contains no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return format, how to determine completion, validation behavior, timing, and optional parameter side effects. Although there is no output schema, the description provides sufficient guidance for an agent to invoke and handle the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining auto-generation behavior for omitted description/tags and validation requirements for contentType='json'. This enriches understanding of how parameters work in practice.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Create a new knowledge-base item for the brand.' It clearly distinguishes from sibling tools like knowledge_list, knowledge_get, knowledge_update, and knowledge_delete by focusing on the create operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 (creating a knowledge item) and includes important workflow details (async, poll get_job until completed). It does not explicitly mention alternative tools, but the sibling names and CRUD context make the usage obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses critical behaviors: synchronous return for minor edits, asynchronous queuing with polling requirement for significant content changes, client-side JSON validation, and expected latency (~15-30s). It also specifies the async return shape and directs to get_job. This is exceptionally transparent about side effects and API behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and front-loaded with the primary purpose. Every sentence adds critical information: the update action, the sync/async dichotomy, JSON validation, and timing. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return values: the updated item for minor edits, and { operationId, status } for significant changes, with polling instructions referencing get_job. It also covers validation and timing. For a tool with 7 parameters and complex async behavior, the description is sufficiently complete to guide an agent without further documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by mapping parameter categories to behavioral outcomes: name/tags/description are minor edits (synchronous), while content changes trigger AI regeneration (asynchronous). This tells the agent which parameters to prioritize and what consequences to expect, going beyond the schema's field-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a knowledge-base item') with a specific verb and resource. It distinguishes itself from sibling tools (create/get/list/delete) and goes further by describing the two modes of update (synchronous minor edits vs asynchronous significant content changes), which uniquely characterizes this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when this tool is appropriate: updating an existing knowledge-base item. It distinguishes between minor and significant content changes, guiding the agent on expected response behavior. However, it does not explicitly mention alternatives (e.g., knowledge_create for new items) or conditions when not to use it, so it misses the full 'when/when-not' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It reveals a non-obvious fact: even detail='full' omits article bodies to keep responses bounded. It also clarifies that `limit` controls row count, not `detail`. This adds valuable behavioral context beyond the schema, though it doesn't describe the response structure or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with 'LIST tool' to immediately set context. Every sentence provides meaningful guidance with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, the key behavioral nuance (body omission), and the critical parameter interaction. It doesn't explicitly state the return type (e.g., array of blog objects), but for a read-only list tool with a well-specified schema, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lacks a description for `limit`, but the tool description fully explains its default, max, and its relationship with `detail`, preventing misuse. It also clarifies that `detail` controls verbosity, not row count, which is not immediately obvious from the enum alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'LIST tool' and clearly indicates the tool lists blogs (blog articles). It distinguishes itself from the sibling tool get_blog_article by explicitly stating that article bodies are omitted and directing the user to call get_blog_article for content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use this tool vs. reading article content, naming get_blog_article as the alternative. It also explains how to get a 'full list' of titles by raising `limit` and keeping `detail='short'`, giving clear usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It discloses the default return fields ('id+name+website'), the effect of detail levels, and hints at the read-only nature of listing. It doesn't mention pagination or rate limits, but for a straightforward list operation, this is adequate and adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each earning its place: purpose, default return behavior, and cross-reference to the alternative tool. It is front-loaded with the primary action and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description is complete. It covers the default return, the parameter options, and directs to get_brand_info for deep dives. No critical information is missing for an agent to effectively select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage of the detail parameter with descriptive enum values, so the baseline is 3. The tool description adds extra clarity by mapping 'short' to id+name+website and instructing when to use medium/full, which reinforces the parameter semantics. There is a slight mismatch with the schema's description (primary label+status vs name+website), but it doesn't negate the added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and clearly identifies the resource 'all brands on your PostKing account'. It distinguishes itself from sibling get_brand_info by explicitly framing the latter as the tool for zooming into a single brand, so an agent knows exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it explains when to use this list tool versus get_brand_info, and instructs how to adjust the detail parameter for different verbosity needs. This clearly tells the agent how to choose between this tool and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It discloses the default behavior (short), the limitation on heavy JSONB (delegated to view_side_page), and that medium/full include draft/live version IDs. This is useful context, though it doesn't mention auth, rate limits, or pagination. Slightly above baseline because of the concrete behavioral insights.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences. The first states the primary purpose and default. The second conveys performance guidance and a practical tip. Every clause earns its place; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations, so the description must cover the essentials. It explains default behavior, what fields appear at different detail levels, and points to the alternative for heavy JSONB. For a list tool with only two parameters, this is complete and sufficient without needing to explain return values in detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes both parameters with 100% coverage. The description adds value by explaining the default for 'detail' and what each detail level includes beyond the schema's enum descriptions, particularly the version ID fields at medium/full. This goes beyond the schema's dry enum explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List side pages attached to a landing page.' It clearly distinguishes from sibling tools like list_landing_pages (lists landing pages, not side pages) and view_side_page (views a single side page in detail). The 'attached to a landing page' qualifier adds necessary context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Offers clear guidance: default detail='short', and explicitly says heavy JSONB is only available via view_side_page, steering agents away from using full detail in this list. Also explains the value of medium/full (version IDs) for spotting unpublished drafts without a second call, helping agents choose the right detail level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It discloses that the tool polls automatically, waits for user interaction, and saves a token (a side effect). However, it does not mention potential timeout or failure behavior, a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action, and includes both the functional behavior and the timing instruction without any filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless login-completion step, the description fully explains what happens (waits, polls, saves token) and when to call it (immediately after login_start). Since there is no output schema, no return details are required. The description is complete for this operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to explain. Per the rubric, baseline for 0 params is 4, and the description adds no parameter information because none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it waits for user approval of the PostKing login code and saves the token. It also distinguishes itself from the sibling `login_start` by indicating it is the subsequent step in the login flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'call this immediately after `login_start`' provides an explicit when-to-use instruction, telling the agent the correct sequencing. This is especially valuable for a two-step login process where timing is critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility and does an excellent job: it discloses that the action is permanent, irreversible, requires explicit confirmation, and causes active clients to stop immediately. This goes well beyond minimal expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action, followed by the critical safety caveat. Every word earns its place; concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description fully covers what the tool does, its irreversible nature, and the required confirmation. No gaps that would hinder correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters with clear descriptions (keyId from list_api_keys, confirm must be true). The description adds behavioral meaning to 'confirm' by framing it as the gate to 'proceed' with an irreversible action, which enhances understanding beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Permanently revoke an API key' with a specific verb and resource, making the action unambiguous. It also includes the consequence ('irreversible', 'stop working immediately'), clearly differentiating it from siblings like create_api_key or list_api_keys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys this is for permanent revocation and requires confirm: true to proceed, implying it should be used for irreversible key invalidation. It does not explicitly name alternatives or exclusion scenarios, but the context is clear enough for a tool of this nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full transparency responsibility. It discloses the best-effort nature of openLicensedOnly and warns to verify usage rights, which is a critical behavioral caveat. It also details the exact output fields for each detail level (short, medium, full), offering rich behavioral context beyond a simple search statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with the core purpose front-loaded in the first sentence. Each subsequent sentence serves a distinct purpose: contrast, return shape, license caveat, follow-up action, and detail semantics. No redundancy or filler is present, though it is slightly dense in the detail-parameter sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema and no annotations, this description covers the essential context: search scope, return fields, license limitation, detail-level output, and downstream import workflow. Remaining parameters (gl, hl, brandId) are adequately documented in the schema, so the description is sufficiently complete without over-explaining.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters, but the generic detail description ('id + primary label + status') does not match this tool's actual output semantics. The tool description corrects this by providing tool-specific meanings for detail levels (url+source, sourceUrl+alt+dimensions, raw), adding significant value beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search Google Images across the whole web for a query', a precise verb+resource statement that immediately establishes what the tool does. It further differentiates from the sibling search_stock_images by noting this tool is broader, removing any ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the alternative 'search_stock_images' for licensed stock libraries, clarifying when to use this broader web search. It also provides a clear next step by pointing to import_asset_from_url to add a result, giving actionable workflow guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly warns: 'Pass `confirm: true` to proceed (this can silently overwrite tags/intent/priority for many keywords at once),' and highlights the requirement that at least one editable field must be supplied. This goes beyond the schema's confirm=true constraint and provides crucial safety context about the bulk overwrite behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tight sentences plus an example, with no wasted words. It front-loads the core action, then covers safety, constraints, workflow, and a concrete example in a compact, scannable format. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, no output schema, no annotations), the description is remarkably complete. It explains the bulk semantics, the confirm requirement, the overwrite risk, the prerequisite workflow, and provides an example. An agent can confidently select and correctly invoke this tool based solely on this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of parameters, but the description adds meaningful semantics: it states that the same values are applied to every id in keywordIds, and adds a logical constraint not in the schema ('At least one of intent, userTags, priority, or excludedFromClustering must be supplied'). The concrete JSON example also clarifies the exact shape of an invocation. These additions raise it above the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Edit userTags, intent, priority, and/or excludedFromClustering across N SeoScoredKeyword rows in one call.' This clearly distinguishes it from sibling tools like seo_edit_keyword (single) and seo_bulk_delete_keywords (delete). The scope ('across N...rows') and the mention of 'Housekeeping op' further clarify its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context and a typical flow: 'call seo_list_keyword_ids with a filter to get the target ids, then pass them here.' It also labels itself as 'not part of the main flow,' which guides when to use it. However, it does not explicitly mention an alternative for single edits (seo_edit_keyword) or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behaviors: bypasses auto-clustering (no LLM call), starts empty, tagged with origin 'manual', created as 'approved', and returns a clear error on duplicate names. This is comprehensive and goes beyond a simple 'creates a cluster'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, but each part earns its place: what it does, how it differs, the workflow, the tagging/approval behavior, and error handling. It's structured logically and not overly verbose for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, lack of annotations, and no output schema, the description provides a complete picture: purpose, lifecycle, error handling, and relationship to sibling tools. Enough for an agent to use it correctly without extra information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description doesn't add significant parameter-specific meaning beyond what the schema already provides. It mentions name uniqueness and returned id, but the schema already documents name as unique and the workflow is explained rather than adding new parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a real, named SEO cluster by hand' and distinguishes it from the auto-clustering pipeline. It specifies the resource (SEO cluster), the verb (create), and the method (manual), setting it apart from sibling tools like seo_generate_clusters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use this tool (manual cluster creation) and what to do next (use seo_create_custom_brief with returned id). It also provides alternatives when a name is already taken, directing to seo_list_clusters, and names the auto-pipeline it bypasses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the operation is async ('Async — returns { operationId, status }'), that polling is required, that omitting clusterId mints a throwaway cluster ('tagged origin="manual"'), and includes a time estimate (~2–5 min). These are non-obvious behavioral traits that help the agent correctly manage the workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each earning its place: purpose, clusterId behavior, async/polling flow, and follow-up/time estimate. It is front-loaded with the core purpose and tightly structured, with no filler or repeated schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 params, nested objects, no output schema, no annotations), the description fully covers the essential context: the async job lifecycle, how to poll for completion, how to retrieve the result, and the side effect of the legacy throwaway cluster. The agent can successfully invoke and complete the workflow from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all 8 parameters (100% coverage) with descriptive text. The description adds minimal extra semantic value beyond the schema, only re-explaining clusterId's role and the legacy fallback, which is also in the schema. Therefore, a baseline score of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a single custom SEO brief on demand' and identifies it as 'the MCP entry point for the generate-one custom-brief flow', which precisely distinguishes it from sibling tools like seo_create_cluster or seo_get_brief. It names the resource and the action, and even contrasts with the legacy REST path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to use the tool: for creating one custom brief on demand, and gives two distinct usage paths (with or without clusterId). It also provides a clear follow-up workflow: poll get_job and then call seo_get_brief, which is actionable guidance for using the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the soft-delete mechanism (sets deletedAt, row stays in DB, filtered out of queries) and the required confirmation flag. This gives the agent a solid understanding of safety and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each with distinct value: mechanism, context, and usage guidance/alternative. No wasted words, and important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-param tool with no output schema, the description covers purpose, behavior, confirmation requirement, usage context, and an alternative. It is fully sufficient for an agent to invoke safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter already described. The description reinforces that confirm must be true, but does not add substantial new meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Soft-delete a single SeoScoredKeyword' with specific behavioral details. It distinguishes itself from sibling tools by noting it is a housekeeping op and contrasting with seo_edit_keyword for a different use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use for obvious junk keywords the auto-pipeline missed.' Provides a clear alternative: 'Prefer seo_edit_keyword with excludedFromClustering=true when you only want to hold a keyword out of the next clustering pass.' Also notes it is 'not part of the main flow.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the async nature, expected duration (~1–2 min), return shape ({operationId, status}), the need to poll get_job, and possible terminal error states (failed/partially_failed/cancelled). This is excellent behavioral disclosure beyond what a schema would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three compact sentences, with the most important information ('Step 4', 'async cluster-generation step') front-loaded. Every sentence adds value: what it does, how long it takes, what it returns, and what to do next. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple async trigger with one optional parameter and no output schema, the description covers the essential context: purpose, timing, return value, polling process, error handling, and subsequent steps in the workflow. It is fully sufficient for an agent to invoke and monitor the operation correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter brandId, including a note that it defaults to the active brand. The description adds no extra parameter details, but per the rubric, baseline 3 is appropriate when schema coverage is high. No additional compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Groups related keywords into topic clusters that become candidate pillar topics.' It also identifies its place in the workflow ('Step 4 of the SEO / GEO flow'), which distinguishes it from other SEO tools like seo_create_cluster or seo_list_clusters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: it is marked as 'Step 4' of the flow, and it gives clear post-conditions: poll get_job until completed, then call seo_list_clusters and seo_generate_roadmap. This tells the agent when to use it and what to do next, effectively differentiating it from alternative cluster-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It clearly states that the default return is short detail and describes what each verbosity level returns (e.g., 'priority, primaryKeywords, clusterId' for medium). It does not mention pagination, sorting, or scope behavior (e.g., brand filtering), but it does disclose the primary behavioral trait — the variable output shape — and points to a sibling for full detail, so it is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, then immediately covers return formats and the alternative single-item tool. Every sentence earns its place — no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 3 optional parameters and no output schema, the description is complete: it explains the default behavior, the exact fields returned at each detail level, and how to access full detail for a single item. It effectively compensates for the lack of an output schema and integrates well with the sibling landscape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds concrete field names for the detail parameter (id, title, status for short; priority, primaryKeywords, clusterId for medium) beyond the schema's generic 'key summary fields + counts'. This enhances parameter understanding despite the schema's already strong descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List roadmap items (blog topics queued for writing)' — a specific verb ('List') and resource ('roadmap items') with a clarifying parenthetical. It further distinguishes from sibling tools by detailing return formats and explicitly naming seo_roadmap_get for single-item detail, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use this tool vs. alternatives: it explains the default 'short' detail and when to switch to 'medium' or 'full', and explicitly directs users to 'Call seo_roadmap_get with detail="full" for a single item's complete detail.' This is strong usage differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses async behavior, expected duration (2–5 min), return format, polling mechanism, error states, and the need to refetch with seo_get_brief. This is modelable behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences: purpose, async flow, and usage guidance. No wasted words; each sentence serves a distinct function. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully explains the return value and next steps for an async operation. It also covers when to use and how to handle completion/errors, making it complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with descriptions (100% coverage), so the baseline is 3. The description adds context about cluster scoping but no additional parameter syntax or format details, so it remains at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Re-runs L3 brief generation for a single brief (scoped to its cluster)', using a specific verb and resource. It distinguishes itself from siblings like seo_edit_brief and seo_get_brief by focusing on regeneration of an existing brief.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use: 'Use when the existing brief's outline is unusable and a structured seo_edit_brief won't recover it.' It also names an alternative (seo_edit_brief) and details the async workflow with polling instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral burden. It discloses the soft-delete mechanism, silent no-op behavior for non-deleted IDs, and that the `restored` count reflects only changed rows, which is valuable operational detail beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no redundancy; each sentence delivers purpose, context, usage, or behavioral nuance, and it is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description provides complete context: what it does, when to use it, how to find input IDs, and the behavior of the restore operation. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are already fully described in the schema (100% coverage), so the description adds no new parameter-level meaning. It reinforces that keywordIds come from seo_list_keyword_ids, which the schema also states, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool undoes a soft-delete by clearing deletedAt on given SeoScoredKeyword ids, making them reappear in the keyword list tools. This specific verb+resource+effect distinguishes it from sibling deletion and listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to use this tool after seo_delete_keyword or seo_bulk_delete_keywords removed something unwanted, and provides the exact method to find deleted ids via seo_list_keyword_ids with includeDeleted=true. It also labels it as a housekeeping operation outside the main flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses safety-relevant behavior: it is 'Read-only dry-run' and does not actually run the storyline. It also reveals the return format ({ estimatedCredits, lineItemBreakdown }), adding concrete behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the critical safety qualifier 'Read-only dry-run.' Every sentence adds value: purpose, usage guidance, and return format. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description provides the expected return shape. It covers what the tool does, when to use it, and that it has no side effects. For a simple two-parameter estimate tool, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for both parameters (brandId and storylineId), so the description adds no additional parameter-level meaning. Baseline of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'estimate' and clearly identifies the resource ('credits required to execute the storyline'). It distinguishes the tool from siblings by explicitly stating it does NOT run the storyline ('without actually running it'), contrasting with storyline_execute. This makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool before storyline_execute to surface costs for user approval. This names the intended workflow, the alternative tool, and the context of use. It implicitly warns against using it when actual execution is desired.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries behavioral disclosure. It states async execution, return format { operationId, status }, polling via get_job, estimated duration (~3-8 min), and a prerequisite cost check. This is rich and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each with a distinct purpose: what the tool does, how to track progress, and a cost warning. Front-loaded with the key verb 'Execute' and no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async tool with no output schema, the description covers return shape, polling mechanism, expected runtime, and a prerequisite cost estimation. This is adequate for an agent to invoke and manage the operation successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (brandId, storylineId), so the schema already provides parameter semantics. The description adds context about storyline execution but doesn't introduce new parameter details beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'Execute' + resource 'storyline' + outcome 'generates content drafts for all selected line items.' Distinguishes from sibling tools like storyline_estimate and storyline_get by clearly stating the action and deliverable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Call storyline_estimate first to surface the credit cost before execution' and 'poll get_job with the operationId until state=completed,' providing clear usage sequencing and follow-up steps. This gives the agent actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses async behavior, the exact return shape ({ operationId, status }), the polling mechanism, and typical duration. This is rich behavioral context beyond what a schema could imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. It front-loads the critical async nature, then purpose, then actionable steps. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description explains the return value, polling, and follow-up workflow. Combined with complete param documentation and clear purpose, it gives the agent everything needed to invoke and handle this async tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are clearly documented ('Brand ID (defaults to active brand)' and 'Storyline ID'). The description does not add parameter-specific syntax but reinforces the storyline context. This aligns with the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Generate the marketing brief for a storyline' and specifies contents (positioning, key messages, audience, timing, tone notes). This clearly distinguishes it from sibling tools like storyline_set_brief and storyline_generate_strategy by naming the exact artifact produced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit workflow guidance is provided: poll get_job until completed, then review with storyline_get, and call storyline_confirm_brief to advance. It also gives a time estimate (~1–3 min) and clarifies that the operation is asynchronous, giving the agent clear when-to-use and how-to-proceed instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It discloses async behavior, returns { operationId, status }, instructs polling get_job until completed, estimates duration (2–5 min), and indicates post-completion steps. These traits go beyond what any schema could convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and async nature. Every sentence adds vital information: purpose, return format, polling, time estimate, and follow-up actions. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully covers the operational context: prerequisites (confirmed brief), return value, polling mechanism, expected duration, and downstream actions. It is complete for an async generation task and leaves no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both brandId and storylineId have descriptions). The description does not add significant parameter-specific meaning beyond the schema; it only mentions 'based on its confirmed brief' which indirectly ties to storylineId. Per the baseline, a 3 is appropriate when schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Generate') and resource ('strategy and line-items for a storyline'), clearly distinguishing it from sibling tools like storyline_get_strategy (review) and storyline_edit_strategy (edit). It states the action and the required prerequisite (confirmed brief), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use this tool: after a brief is confirmed. It also provides a clear workflow: poll get_job, then review with storyline_get_strategy, and optionally edit or modify line items. This directly gives alternatives and next steps, satisfying the 'when/when-not/alternatives' criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses the financial side effect ('triggers a real charge'), the two response shapes (headless success vs. checkout fallback), and the follow-up actions (announce payment details, do NOT call billing_wallet to poll). This gives an agent a complete picture of side effects and state transitions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured: it front-loads purpose, then presents an IMPORTANT warning, then details both response shapes and the appropriate actions. Each clause serves a functional purpose, though the SKU list is repeated from the schema (with added pricing).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema, the description fully enumerates the two possible response formats and exactly how the agent should behave for each (announce payment ID and done vs. hand over checkoutUrl). It also names sibling tools (billing_list_packs, billing_wallet) to position this tool in the workflow, making it contextually complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers packSku with an enum and description (100% coverage), so the baseline is 3. The description adds value by mapping each SKU to a price and credit amount (e.g., 'agent_4 ($4 / 160 credits)') and by tying pack selection to explicit user consent, which enriches the parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Top up credits by charging the account's card on file (Stripe off-session)'. It also distinguishes itself from sibling tools by mentioning the headless path and referencing billing_list_packs and billing_wallet, making the tool's function and scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Only call this tool after the USER has explicitly chosen a specific pack — it triggers a real charge.' It also provides alternatives: 'To show the user their options first, call billing_list_packs and present the results; do NOT pick a pack on the user's behalf.' This is exemplary when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description thoroughly discloses the async nature (returns quickly and does not block), explains what happens in each status case, warns against fabricating the page or re-calling, and surfaces that warnings are passed verbatim. It also describes the behavioral difference between research and simple modes in detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every sentence provides essential operational detail (async behavior, mode semantics, input strategies, return values). For a tool with this complexity, the length is justified and the content is organized with clear separators (hyphens and semicolons). It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 12 parameters, this description fully covers behaviors, return values in both success and pending scenarios, parameter usage guidance, and error handling (poll get_job, don't fabricate, don't re-call). It leaves no major gaps for an agent invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all 12 parameters with 100% coverage, so the baseline is 3. The description adds extra meaning for key parameters: mode (explains crawl vs no-crawl tradeoff), seedData ('this is how you feed your own data and avoid a crawl'), and options (omit to let research mode discover them). This goes beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Create') and resource ('comparison / X vs Y / best <category> page for the brand'), and explicitly distinguishes itself by saying 'WITHOUT going through the full SEO cluster → brief flow'. This clearly identifies what the tool does and differentiates it from the standard SEO flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly contrasts the two modes ('research' vs 'simple'), gives guidance for when to choose each: 'When your inputs are sparse... prefer research' and 'simple... best when you already have the facts or just want a quick draft'. It also tells the agent not to call again while pending and to use get_job instead, which are clear when/when-not directives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels. It discloses async behavior, typical duration (~1–3 min), credit usage, return shape (`{operationId, status}`), polling instructions via get_job, possible job states, and the critical behavior that supplying seeds REPLACES (not merges with) auto-generated seeds. This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, but every sentence carries useful information: async nature, cost, return value, polling, seeds behavior, constraints, and next step. It is front-loaded with the step and purpose. Slightly long but appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description thoroughly explains the return value and lifecycle (poll until completed/failed/partially_failed/cancelled). It covers default behaviors, seed customization, cost, and follow-up tool (seo_categorize). For an async, cost-incurring tool with 3 parameters, this is complete and sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions are already detailed (e.g., seeds replacement behavior, default brandId, autoScore default). The main description adds minimal extra beyond the schema, but it does emphasize that 'the only other thing the agent can tweak is autoScore' and reinforces the seeds format (3-20 short phrases, 2-4 words, no jargon). This adds a bit of practical context above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'expands seed keywords into the full keyword universe.' It also positions it as 'Step 2 of the SEO / GEO flow,' distinguishing it from siblings like seo_categorize and seo_generate_roadmap. The verb 'expands' and the resource 'seed keywords' make the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it is 'Step 2' of the flow, and it instructs 'After completion, call seo_categorize.' It also explains when to use the default auto-derivation versus passing seeds: 'By default the server auto-derives... Pass seeds to steer expansion yourself instead.' This gives the agent clear decision guidance for tool usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description fully carries the burden. It discloses async behavior, return payload shape, polling requirements, success/failure states, concurrency limits, and the 'already_running' notice. This goes beyond a simple statement of side effects and gives the agent a complete mental model of the tool's runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written in four sentences, each earning its place. It front-loads the core purpose, then covers required parameters, async workflow, and constraints without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (async, stateful, concurrent limits) and lack of output schema, the description explains everything an agent needs: how to specify changes, what response to expect, how to poll, and typical timing. It also references sibling tools appropriately, making the description self-sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter descriptions are already clear. The description adds value by emphasizing that `sections` is REQUIRED, giving concrete examples, and directing users to preview_audience_edit to discover valid keys. This is above the baseline, though much of the parameter meaning is already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs an async LLM AI edit of the brand's audience/ICP, using a specific verb ('ai-edit') and resource. It distinguishes itself from sibling tools like get_audience (read) and preview_audience_edit (preview) by emphasizing that it edits and returns an operationId for async polling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: describes the intended use for editing audience sections, instructs users to call preview_audience_edit first if unsure about valid section keys, and warns about the single-running-edit constraint. It also specifies the async polling workflow and typical duration, offering clear when-to-use and when-to-check alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It thoroughly discloses non-blocking behavior, 10-credit deduction per variation, single postId for multiple variations, polling with get_post, duplicate-draft risk, and visuals not being attached automatically. This is exceptional transparency for a complex async tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but every sentence carries essential information—no fluff. It could be improved with bullet points or section headings, but the dense single-paragraph format is acceptable given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, no output schema, and no annotations, the description is exceptionally complete. It covers async processing, credit costs, variation handling, post-save workflow, repurposing flow, visual options, and the editInVisualEditor URL—leaving very little unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, setting a baseline of 3, but the description adds substantial meaning beyond the schema. It explains that omitting `theme` results in a random topic, that variations >1 all return under a single postId, and that free-text `theme` overrides `themeId` when both are given. This significantly enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement: 'Generate AI content for a platform.' It further distinguishes itself from sibling tools like generate_bulk_posts and generate_post_carousel by detailing single-post generation with variations and asynchronous return behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit workflow guidance is provided: 'After generating, use create_post to save a chosen variation, then approve_post to schedule it.' It also names alternatives (repurpose_content) and warns against repeated calls while pending, giving clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the asynchronous behavior: returns quickly with an operationId and status, doesn't block until completion, requires polling get_job, and warns against duplicate calls while pending. It also defines what each detail level returns, giving users a clear picture of the operation's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with purpose, exclusions, and async behavior. While longer than typical, it covers many necessary nuances without redundancy; however, it could be slightly tightened to improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema or annotations, the description covers the full async workflow, parameter semantics, return detail levels, and error/retry guidance. This makes the tool's behavior and expected outcomes remarkably complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description goes beyond the schema by explaining the semantics of mode ('generate' writes from prompt, 'rewrite' reworks sourceText), providing examples for prompt and purpose, and detailing the length and detail options. This significantly enhances the agent's ability to set parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates or rewrites general-purpose email-style/formal text, with specific examples like follow-up emails and cover letters. It explicitly distinguishes itself from sibling tools (generate_post, rewrite_with_voice, rewrite_text), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance: 'This is NOT for social media posts — use generate_post' and 'NOT for a simple voice-only rewrite... use rewrite_with_voice or rewrite_text.' It also specifies when to reach for generate_text, such as when mode selection, a stated purpose, or target length is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: return fields, possible states, wait polling interval, maxWaitSeconds clamping, result/errors semantics, and detail levels. It explains the outcome on completion versus failure and the need for re-polling long jobs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense, with a clear structure: primary use, prohibition, return shape, polling guidance, waiting behavior, and parameter details. Every sentence contributes necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-param tool with no output schema, this description is remarkably complete. It explains the return structure, state transitions, error handling, parameter semantics, and usage context, leaving little room for ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all params with descriptions, but the description adds value by elaborating detail levels (short/medium/full exact fields), the wait polling cadence, and how pollUrl can be a bare operationId with brandId. This goes beyond the schema, though some information is already present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks the status of ONE specific operation by operationId or pollUrl, explicitly distinguishing it from list_operations. It names the resource (an Operation row) and the verb (poll/check), making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use (to check a single operation) and when not to (don't use list_operations for specific ops). It also provides guidance on using wait:true instead of repeated polling, and which tools return operationIds, making it easy to select.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries behavioral disclosure. It reveals the tool is non-mutating, that medium truncates before/after to 200 chars, full returns untruncated data, error is populated on failure, and instructs the agent to surface the error. No contradictions with annotations (none present).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place. It front-loads the core purpose, then systematically covers detail modes, error handling, and next-step behavior. Nothing is redundant or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description compensates by fully describing the return structure for each detail level, including the error field. It also connects to sibling tools and provides operational sequence (poll → apply). Given the tool's complexity and missing annotations, this description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond schema: it explains that operationId comes from vibe_edit_landing_page, specifies what each detail level returns, and notes that index/path from the medium response should be used in apply_vibe_edit. This goes beyond the schema's generic parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Poll vibe (AI) edit session status' — a specific verb ('poll'), resource ('vibe edit session status'), and clear scope. It distinguishes from siblings by explicitly stating 'this tool never applies anything' and referencing apply_vibe_edit as the follow-up.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: when status is 'completed', call apply_vibe_edit next. Also explains when to use each detail level ('medium' is the REVIEW view, 'short' is cheap, 'full' is raw), and how to use resulting values to select a subset in apply_vibe_edit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (none provided), the description discloses key behaviors: synchronous execution, 0 credit cost, requirement of existing brand pool, and detailed output components (angles, promotion mode, buyer intent, match score, key rule). It also explains the verbosity modes (short/medium/full) which affect response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds value: purpose, output structure, workflow position, prerequisites, and verbosity levels. It is front-loaded with the primary purpose and uses concise bullet-like notation for detail modes, avoiding redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description carries full burden. It covers the input requirements, output fields, detail levels, flow step, prerequisite, and cost/behavior. For a tool with 5 parameters and complex return data, this is comprehensive and leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining when to use postId vs title+content ('by id, or pasted title+text') and clarifies that brandId defaults to active brand. The detail enum is also interpreted in the context of this tool's output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: given brand content, return up to 8 best-fit subreddits with posting angles and metadata. It clearly distinguishes itself from siblings by naming the output (subreddit suggestions) and referencing the downstream reddit_rewrite step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly places the tool in a workflow: 'Flow step 2 of 4: pool → SUGGEST → rewrite → list_posts' and states the prerequisite: 'Requires the brand pool to exist — call reddit_generate_pool first if it doesn't.' This provides clear when-to-use and sequential context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the destructive cascading behavior: deletes every SeoRoadmap item and its brief, clears cluster links on blog articles and keywords, and is NOT UNDOABLE with no soft-delete. It also notes the operation is irreversible, which is critical behavioral context. No contradictions with annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense, with no filler words. Every sentence adds necessary detail: the action, cascade consequences, non-deletion of related items, irreversibility, housekeeping context, confirm requirement, and alternative tool. Front-loading the core action and consequences makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a destructive, high-complexity tool with no annotations and no output schema. The description fully covers the operational context: what gets deleted, what doesn't, how to confirm, reversibility, and the preferred alternative. It is complete enough for an agent to safely decide whether and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description enhances parameter understanding by explaining that confirm: true is required to proceed and that clusterId should come from seo_list_clusters. It also describes what happens to related entities, providing meaning beyond raw schema field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Hard-delete a cluster,' clearly stating the action and target resource. It distinguishes itself from sibling seo_reject_cluster by explaining the difference in destructiveness and reversibility, making the purpose highly unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: it states this is a 'housekeeping op — not part of the main flow', requires confirm: true to proceed, and explicitly recommends seo_reject_cluster as the reversible alternative when the goal is just to remove from the active pipeline. This clearly covers when to use and when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the destructive nature ('Not undoable', 'deletes the source cluster') and the precise scope of changes ('target cluster's own name/description/keywordsMeta/contentMix are NOT changed', only FK relations move). This goes beyond simple annotation cues and gives the agent a clear safety and side-effect profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: it starts with the core action, details what moves, warns about irreversibility, gives the trigger condition, explains what does NOT change, and suggests a follow-up. It is thorough but not repetitive, and front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema and only 3 simple parameters, the description is remarkably complete. It covers the operation's effects, transitive behavior (briefs follow roadmap items), non-effects, reversible status, usage context, and post-merge follow-up. Nothing significant appears missing for an agent to safely invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides good descriptions (clusterId survives, sourceClusterId deleted). The description adds meaning by clarifying that the merge only moves FK relations and does not update target metadata, which helps the agent understand the consequences of each parameter beyond the basic schema wording. This is above the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Merge one cluster into another') and enumerates exactly what gets reassigned (keywords, roadmap items, briefs, blog articles) and that the source is deleted. This clearly distinguishes it from sibling tools like seo_delete_cluster and seo_edit_cluster.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this when 'seo_list_clusters or a rescan report shows near-duplicate clusters that should be consolidated' and frames it as a 'housekeeping op — not part of the main flow.' It also recommends seo_edit_cluster afterward if the target's keywordsMeta needs updating, providing concrete alternatives and follow-up guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses 400 validation errors on shape mismatch, the three edit modes, AI-pass behavior, the flat-document behavior for text pages, draft version creation, and draft-only until published—all critical behavioral traits beyond what a schema could convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries operational value. It is front-loaded with the core purpose. The only minor issue is that it is a single dense paragraph; structured sub-sections could improve readability, but it is not wordy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and absent output schema, the description covers all needed workflows: inspection via view_side_page, the three edit modes, validation errors, version creation, and publishing requirements. It also explains the text-page special case and the nuance of instructions as annotation-only when combined with fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds substantial meaning: it explains the three parameter combinations (fields, field+value, instructions), the dot-path syntax with an example (title.prefix), the typed shapes for landing and comparison sections, and the sectionId symmetry for text pages. This goes far beyond the individual property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates one section of a side page with structured, typed fields, distinguishing it from the simpler edit_side_page shortcut. It specifies both landing-section and comparison-section shapes, and the flat text-page case, making the resource and scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use view_side_page(detail:'full') first to see the current section shape. Provides clear alternatives: edit_side_page for text-page direct writes, and explains when to use fields vs field+value vs instructions, including that instructions combined with fields does not trigger an AI pass.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so excellently. It discloses the side effect of published:true (sets published pointer to latest draft), the non-destructive behavior of published:false (keeps last-published marker), and the exact response field (publishedVersionId), giving the agent a clear mental model of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the action and resource, then proceeds logically through publish and unpublish semantics, ending with the response field. Every sentence adds valuable operational detail without fluff, making it dense but clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, no output schema) and the absence of annotations, the description covers all essential aspects: what it does, how it behaves for both flag values, the versioning nuance, and the return value. An agent has enough to invoke it correctly without further investigation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic context beyond the schema by explaining the nuanced behavior of the 'published' boolean parameter (true publishes draft, false hides but preserves restore capability) and the 'slug'/'sideKey' parameters are self-evident from their schema descriptions. This elevates it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Publish or unpublish') plus the resource ('a side page') and explains the core behavior. It clearly distinguishes from sibling tools by focusing on the publish/unpublish action rather than editing or viewing, and even references how it relates to edit_side_page / set_side_page_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool: to make draft edits live via published:true, and to hide a page while retaining the ability to instantly restore it via published:false. It also states that the response includes publishedVersionId, eliminating the need for a follow-up view_side_page call, which is practical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses key behaviors: it does not access stored templates, requires explicit caller-supplied candidates, is synchronous, and returns an ordered array of template IDs. This goes beyond the schema and gives the agent confidence about side effects and invocation flow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five tight sentences, each providing distinct information: what it does, a critical caveat, synchronous behavior, input source, and return format. No redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description covers purpose, input source, return shape, and behavior. It even prevents a common mistake by warning against assuming server-side template reading. This is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds valuable guidance that the templates parameter should be the full-detail output from template_list, with the return format clarified as ordered IDs. This raises it to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: an AI re-ranker that scores and picks the N best-fitting templates from a caller-supplied list. It explicitly distinguishes itself from tools that read stored templates by noting the caller must supply candidates, differentiating from sibling template_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: call template_list first, then pass the full-detail templates array to this tool. It also states what the tool does NOT do (does not read stored templates server-side) and that it is synchronous/no polling needed, giving clear context versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: synchronous execution (no polling), side effects (Main-LP changes create a new draft version), and clear semantics (clear:true or assetId:null). It also explains the difference between single and array slots. This is thorough and goes beyond what is obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, with every sentence adding valuable information. It is front-loaded with the primary purpose and then systematically covers key details (slot keys, array vs. single, side pages, clearing, synchronous behavior, draft versioning). No redundant or fluff content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is remarkably complete. It explains prerequisites, slot key discovery, input variations, target page selection, clearing options, and side effects. It provides the agent with enough context to invoke the tool correctly without additional lookups.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema covers all parameters (100% coverage), the description adds substantial meaning: it explains that assetId is for single slots and assetIds for array slots, that clear:true or null can empty the slot, and that sidePageSlug targets a specific side page while pageKey is ignored. This provides critical disambiguation beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Assign, reassign, or clear the asset in a landing-page or side-page slot.' It uses specific verbs and identifies the resource (asset slot). This distinguishes it from sibling tools like list_asset_slots and list_assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: when to use this tool (to assign/clear assets in slots), prerequisites (asset in brand library, matching media type), and references to alternative tools for discovering valid slot keys (list_asset_slots) and managing assets (list_assets, upload_asset, import_asset_from_url). It also clarifies synchronous behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description must disclose side effects. It thoroughly covers draft-version creation, non-destructive writes, draft-only publishing, 404 on rename, background reference rewrites, and the slugRewriteOperationId polling requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Long but information-dense; each sentence adds new behavioral or contextual detail, organized into clear segments.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-param tool with no output schema, the description covers parameter applicability, side effects, versioning, publishing, and the async operation response field, leaving no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds critical semantics: title vs name distinction, flat document vs section overrides, partial-write preservation, and instructions not triggering AI edits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Update') and resource ('side page'), scopes to metadata and content (type:text only), and distinguishes from siblings by explicitly naming set_side_page_section for non-text pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when NOT to use this tool (landing/comparison pages) and directs to set_side_page_section; also explains versioning and publishing alternatives (list_side_page_versions, set_side_page_state).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers thoroughly. It discloses the replacement semantics of keywordsMeta, warns that "Sending a partial array will drop the missing members," explains contentMix normalization of rounding drift, notes duplicate rejection in briefAssignments, and illustrates the exact shape of entries. This level of detail goes far beyond a minimal description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose, then uses clear headings and examples to organize the lengthy but necessary details. Every sentence contributes actionable information—no filler or repetition—making the length justified and the structure easy to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a complex tool with 8 parameters, nested objects, and no output schema, the description covers all necessary ground: field semantics, membership management workflow, contentMix constraints, briefAssignments rules, and examples. It also cross-references sibling tools for fetching current state, making it self-sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already has 100% parameter coverage, the description adds meaningful semantics not present in the schema: the exact structure of keywordsMeta entries, how to fetch the current array, the allowed types for briefAssignments, and the behavioral caveat about partial arrays. This enriches the bare schema definitions and clarifies the intent behind each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Edit a cluster's name, pillarKeyword, description, keywordsMeta, contentMix, and/or briefAssignments." It clearly distinguishes this from related cluster operations by framing it as a "Housekeeping op" and focusing on field-level edits, while sibling tools like seo_merge_clusters or seo_delete_cluster handle different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool for membership changes: "there is no separate add/remove-member endpoint," and provides step-by-step instructions referencing seo_list_clusters and seo_list_keywords. It also sets a precondition ("At least one field must be supplied") and includes practical examples for renaming and removing a member, leaving no ambiguity about the intended workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: default returns all statuses, statusBreakdown matches dashboard counts, in-flight briefs may not appear, and response shapes for each detail level. This goes far beyond minimal requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured and front-loaded with the most critical default behavior. Every sentence provides necessary context for a complex 9-parameter tool, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the response shape, detail levels, filters, pagination, and edge cases like in-flight briefs. It is complete for a list tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds significant meaning: clarifies status/type CSV formats, explains detail levels with specific fields, describes pagination via cursor, and defines the response shape. This is substantial added value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns all briefs across every status, with specific scope and behavior. It also explicitly distinguishes itself from seo_get_brief for inspecting a single brief, 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: do NOT add a status filter unless asked, check list_operations/get_job for in-flight generation, and use seo_get_brief for single-brief details. This gives clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![postking-mcp MCP server](https://glama.ai/mcp/servers/bitsandtea/postking-mcp/badges/card.svg)](https://glama.ai/mcp/servers/bitsandtea/postking-mcp)

Score Badge

Copy to your README.md:

[![postking-mcp MCP server](https://glama.ai/mcp/servers/bitsandtea/postking-mcp/badges/score.svg)](https://glama.ai/mcp/servers/bitsandtea/postking-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/bitsandtea/postking-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server