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

Annotations already establish it is a safe read, but the description adds real behavioral context beyond them: the auth requirement ('Requires the project.read grant') and the return contract ('Each check comes back with the one action that fixes it'), which matters because there is no output schema. Rate limits or response format details are absent, keeping it 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.

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

Three sentences, front-loaded with purpose then usage then auth requirement, with no filler. The middle sentence is long and does double duty, but every sentence earns its place.

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

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

For a single-parameter diagnostic with no output schema, the description covers what it checks, when to call it, the auth requirement, and what it returns (a fixing action per check). Nothing an agent needs to invoke it correctly is missing.

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

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

Only one parameter, and schema description coverage is 100% (the schema documents the prj_... format). The description adds nothing about the parameter, so the baseline of 3 for a fully covered schema is appropriate.

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

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

States a specific verb and resource ('Checks whether a project is really connected to a website') and then enumerates the three concrete sub-checks: key presence, whether a site has ever used it, and whether views arrive from rendering pages. This is clearly a diagnostic tool, distinct from siblings like get_integration_guide or get_content_analytics, so an agent can select it without opening the schema.

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

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

Gives explicit triggering conditions: 'ALWAYS call this after wiring up an integration, and always when somebody says views or analytics are zero.' It even explains the discriminating scenario (a site that fetches content but reports nothing), which tells the agent when this is the ONLY right tool.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that the full key is returned exactly once and cannot be retrieved afterwards, that it is read-only with published-content-only access, the browser-exposure caveat, and the required apikey.write grant. This is exactly the kind of one-time-secret and auth context an agent must surface.

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

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

Purpose is front-loaded in the first clause, followed by the one-time-secret warning, the safety scoping, the alternative, and the grant requirement. Every sentence carries operational information; nothing is filler.

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

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

With no output schema, the description correctly compensates by explaining the return value (the full key, shown once). Combined with the permission requirement and safety constraints, an agent has everything needed to call this correctly and instruct the user.

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

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

Schema description coverage is 100% and only two parameters exist, both documented in-schema (projectId as `prj_...`, name as a human-readable purpose label). The description adds no parameter-level syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource with scope: 'Mints the credential a website reads this project with', then narrows it to a read-only key returning published content only. This clearly distinguishes it from siblings like list_api_keys and from the agent token mentioned in the description.

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

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

Gives explicit routing guidance: prefer this over handing a site the agent token (which can write and delete), safe in a server environment, and NOT safe in browser code unless an allowed-origins list is configured. The when-to-use condition and the alternative are both named.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) already establish this as a non-destructive write. The description adds real value beyond that by clarifying the entity is content rather than an identity/account and that no invitation or access is granted — a common and costly confusion. It omits other traits such as uniqueness of name/slug or what happens on duplicate creation.

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

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

Two short sentences, front-loaded with the entity definition and followed immediately by the scope exclusion. No filler, and every clause carries a distinct piece of meaning.

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

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

It fully answers 'what kind of thing is this and what is it not', which is the hardest question for this tool. But with no output schema and four undocumented input parameters, an agent still lacks guidance on which fields matter, whether name/slug must be unique, or what identifier comes back.

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

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

Schema description coverage is only 20% (just projectId), and the description contributes nothing about parameters. With 5 parameters, four of which (name, slug, bio, email) are undocumented in both the schema and the description, the description fails to compensate for the coverage gap as it must at this level.

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

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

The description defines what an author entity is ('A byline') and sharply scopes the tool by stating it is not an account or an invitation. Combined with the name/title 'Create an author', the agent can tell this apart from account-provisioning or invite tools, though the description itself never states the create verb directly.

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

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

It gives an explicit when-not: this does not create accounts or invite people, and access to the workspace is a separate dashboard action. That is a genuinely useful boundary. It does not, however, point to any sibling tool (e.g. list_authors) for the related read workflows.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/safety profile is covered. The description adds value beyond them by disclosing the content.write authorization requirement and the three-level nesting ceiling, both of which shape whether the call is legal. It still omits duplicate-slug behavior and error semantics.

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

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

Three short sentences, no filler, with the most consequential facts (hierarchy limit, required grant) front-loaded rather than buried. Every sentence earns its place.

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

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

For a 5-parameter create tool with no output schema and 40% schema coverage, the description covers scope and authorization but leaves the agent guessing about return value, duplicate-handling, and the undocumented name/slug/description fields. Adequate but with clear gaps.

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

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

Schema description coverage is only 40%, so the description must compensate. It does add meaning for parentId ('a subsection of one when you pass parentId', plus the three-level depth limit), but name, slug, and description remain undocumented in both places, and nothing explains slug generation or uniqueness.

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

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

The description defines the resource precisely (a blog section, or a subsection when parentId is supplied) and the title/name supply the create verb. It is clear against siblings like update_category and delete_category, though the description text itself never states the creating action and doesn't name those siblings.

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

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

It gives a real prerequisite ('Requires the content.write grant') and a structural constraint ('three levels deep at most'), which tell the agent when the call will succeed. However, there is no explicit guidance on when to choose create_category versus update_category or list_categories — usage is only implied.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds real value beyond that: the default draft state and the specific grants required (content.write, plus content.publish when status is 'published'), including the conditional dependency between status and grant.

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

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

Three tight sentences, front-loaded with the core action and the default behavior, with the permission detail last. No wasted words.

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

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

For a 13-parameter create tool with nested objects and no output schema, the description covers the highest-stakes decision (draft vs publish) and the auth prerequisites, which is the critical context. Minor gaps remain around side effects like auto-created tags and slug derivation, but those live in the schema.

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

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

Schema description coverage is 62% and the schema already documents status defaults, publishedAt and scheduledAt constraints. The description reinforces the status/grant relationship but adds little beyond the schema for the other 12 parameters (excerpt, authorId, categoryId, bodyFormat, seo). Baseline 3 for moderate coverage the description only partially compensates for.

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

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

The description opens with a specific verb+resource ('Writes a new post'), which cleanly distinguishes it from update_post/delete_post siblings. The draft-default framing further pins down exactly what kind of post this produces.

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

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

It gives clear contextual guidance: default to draft, and 'publishing is a decision the person should make' steers the agent toward draft unless told otherwise. It stops short of naming when-not-to-use or an alternative tool, but the draft/publish decision guidance is explicit.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered structurally. The description adds the auth requirement (project.write grant), which is genuine behavioral context, but omits slug derivation behavior, uniqueness/idempotency handling, and what the call returns.

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

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

Three short sentences with no padding, but the first is a fragment that omits the action verb, so the text is under-specified rather than genuinely tight. The most important fact (that this creates a project) is not front-loaded.

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

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

No output schema exists, so the description should carry more burden for a 5-parameter creation tool; it covers the grant requirement and the value of two fields but leaves name, slug, websiteName, and the response shape unexplained. Adequate as a minimum viable definition, incomplete for the tool's actual complexity.

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

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

With only 40% schema description coverage across 5 parameters, the description must compensate, and it partly does by explaining why description and websiteUrl matter downstream (readability in project lists). It says nothing about name, slug, or websiteName, and 'website fields' is vague about which of websiteUrl/websiteName it means.

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

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

The description never states a verb — 'A new site inside this workspace' is a noun fragment describing the result, so the create action is only inferable from the tool name and title. It does define the resource (a project is a site scoped to a workspace), which loosely differentiates it from create_workspace, but there is no explicit 'creates a project' statement.

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

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

'Requires the project.write grant' is a concrete prerequisite, which is real guidance. However, it says nothing about when to use this versus create_workspace/create_category, nor about duplicate-name/slug conditions or what happens if the caller already has a project with that slug.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false), so the description earns credit for disclosing the key cross-tool behavior: sibling write tools implicitly create missing tags, making this usually redundant. It does not say what happens on a duplicate name/slug (error vs. no-op vs. update), which is the main remaining behavioral gap.

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

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

Two tight sentences with the 'usually unnecessary' caveat front-loaded so the agent can bail out early. No filler.

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

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

Covers the when-to-use decision well, but for a mutation tool with no output schema and no annotation coverage of failure modes, it omits return value and duplicate-handling semantics. Adequate but with clear gaps given the 4-parameter surface.

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

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

Schema coverage is only 25% — just projectId is documented. The description mentions 'description' only obliquely as a reason to use the tool, and says nothing about name, slug, or the uniqueness/format expectations for them. With three undocumented parameters, the description does not compensate for the coverage gap.

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

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

The description makes clear this creates a tag and, crucially, distinguishes it from create_post/update_post which auto-create tags. The core verb is implied rather than stated outright ('set one up'), but the resource and its role in the tag lifecycle are unambiguous.

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

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

Explicitly names the default alternative behavior ('create_post and update_post create tags they do not find') and gives the two precise conditions that justify this tool: a tag needing a description, or pre-registering one before writing. An agent knows exactly when NOT to call it.

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

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

Annotations only declare this is a non-read-only, non-destructive mutation. The description goes well beyond that: it discloses the one-time `agentToken` in the response, that it cannot be retrieved again, that it must be shown to the user for saving, and that the current token lacks rights in the new workspace. That is exactly the behavioral context an agent cannot get from structured fields.

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

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

Three tight sentences, front-loaded with what is created and followed by the highest-risk detail (the one-time token). No filler; every clause conveys a fact the agent must act on.

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

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

There is no output schema, so the description must explain the return value — and it does, including the agentToken, its one-time nature, and its unusability by the calling token. Combined with the grant requirement, an agent has everything needed to call this correctly and handle the result.

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

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

There is a single parameter and schema description coverage is 100% ('What the company or site is called.'), so the schema already carries the meaning. The description adds no format, constraint, or naming guidance beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Creates a workspace') plus an important scope detail: it also creates a first project, owned by this token's account. That distinguishes it from the sibling create_project, which creates a project inside an existing workspace.

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

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

Gives a clear precondition ('Requires the workspace.create grant') and a critical post-condition warning ('this token cannot act in it'), which tells the agent when the returned token is and isn't usable. It does not explicitly contrast with create_project or state when to prefer one, so it falls short of full routing guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, yet the description adds substantial context beyond them: posts are preserved and merely become uncategorized, subcategories retain their paths, and human confirmation is required. These are exactly the consequences an agent needs before calling a destructive tool and are not derivable from the schema or annotations.

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

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

Three short sentences, no filler, and the most consequential fact (posts are not deleted) is front-loaded. The confirmation warning is placed last, matching the order in which an agent should act.

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

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

For a simple two-parameter destructive tool with no output schema, the description covers the key blast-radius question (what is and isn't destroyed) and the approval requirement. It omits whether the deletion is permanent/recoverable, required permissions, and the response shape, which are minor gaps but would be useful for a destructive call.

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

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

Schema description coverage is 50%: projectId is documented in the schema, while the required 'id' has no description anywhere. The description adds nothing about either parameter, so the undocumented required 'id' is only inferable from the tool name. Adequate given 'id' is largely self-evident, but no compensating detail is provided.

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

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

The description's framing ('Posts filed under it... stop having a category', 'Its subcategories keep their path') makes it unambiguous that a category is being removed, which combined with the name/title pins down the verb+resource. It does not explicitly state 'deletes a category' in prose, but the consequences only make sense for that operation. It does not contrast with siblings like update_category, but the resource is clear.

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

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

'Confirm with the person first' is an explicit prerequisite for invoking this tool, which is genuine usage guidance for a destructive operation. It does not name alternative tools (e.g., update_category to rename instead of delete) or state when deletion is inappropriate, so it stops short of the top score.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=true; the description goes well beyond that by revealing the delete is *soft*, what actually changes (content stops being served, the slug is released for reuse), and the authorization grant required. Those are the exact behavioral facts an agent needs before calling 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.

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

Three short sentences with zero filler, ordered by importance: effect, then confirmation requirement, then permission prerequisite. Nothing could be removed without losing information.

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

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

For a two-parameter destructive tool with no output schema and annotations covering the safety profile, the description supplies the important missing context (soft delete, effects, grant). It does not mention reversibility/restore paths or error conditions, but nothing essential to correct invocation is absent.

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

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

Schema description coverage is 100% and both parameters (id, projectId) are documented in the schema, including the prj_ prefix and the CMSKITE_PROJECT_ID default. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Soft-deletes a post") and immediately qualifies the semantics with the observable consequences: it stops being served and its slug is freed. That nuance is exactly what separates this from a hard delete, so an agent can identify the operation without opening the schema.

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

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

Gives a clear precondition ("Requires the content.delete grant") and a workflow instruction ("Confirm with the person first"), which is real when-to-use guidance for a destructive operation. It stops short of naming alternatives or stating when deletion is inappropriate (e.g. prefer update_post for edits), so it isn't fully 5-level.

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

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

Beyond the readOnlyHint/destructiveHint=false annotations, the description discloses that results are served from rollups and are therefore constant-size regardless of traffic, and that the call requires the analytics.read grant. It also warns that all-zero results usually indicate a tracking failure. This is meaningful operational context.

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

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

Three sentences, front-loaded with the purpose before the return shape, then the rollup behavior, then the escalation rule and grant requirement. Every sentence adds information an agent can act on; there is no filler.

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

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

With no output schema, the description usefully sketches the return shape (totals, daily series, top posts) and names the required grant, so an agent can call it confidently. It stops short of describing key names or whether the series can be sparse, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so all four parameters (projectId, from, to, topPosts) already carry their own descriptions, defaults, and bounds. The description's phrase 'over a date range' adds no format or boundary 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.

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

States a specific verb+resource ('What readers did with a project's posts') and enumerates the shape of the answer: totals, a daily series, and best-read posts. It implies project-level scope, which separates it from the per-post sibling get_post_analytics, but it never names that sibling, so the differentiation is inferred rather than stated.

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

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

It provides a concrete when-to-escalate rule: if everything is zero, call check_integration, with the reasoning that it is usually a tracking problem. That is real routing guidance, but it gives no guidance on when to prefer this aggregate view over the sibling get_post_analytics for a single post.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Does not read or change anything in CMSKite.' It adds real behavioral context beyond the annotations by disclosing the consequence of skipping it (silent loss of analytics) and the fact that a downstream check is required to validate the result.

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

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

Front-loaded with the purpose and the sequencing instruction, and every sentence carries weight. The framework-to-package sentence overlaps somewhat with the schema's own enum description, and the guidance-plus-warning content runs slightly long, but there is no filler.

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

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

There is no output schema, so the description must explain returns, and it does: what to install if anything, the files to write, and which key belongs on the server versus in the browser. Combined with the workflow sequencing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a language-level mapping not present in the schema (JS/TS use the cmskite package; PHP, WordPress, Laravel, Python and plain HTML use raw HTTP with no dependency), which helps an agent reason about the enum's intent rather than just its allowed values.

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

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

States a specific verb and resource ('the official way to connect a project to CMSKite') and enumerates the concrete deliverables (what to install, files to write, which key goes server-side vs browser). It is clearly distinguishable from the sibling check_integration, which it explicitly frames as the verification step rather than the guidance step.

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

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

Explicit sequencing: 'Call this BEFORE writing any integration code by hand' and 'Finish by calling check_integration'. It also names the failure mode that motivates using it (hand-rolled fetch wrappers miss view tracking) and names the alternative tool that detects that failure, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that the response includes the full body (not a summary), but says nothing about permission requirements or what happens when neither id nor slug is supplied.

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

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

A single eleven-word sentence with the outcome ('one post with its full body') front-loaded and the lookup keys trailing. Zero filler; every clause earns its place.

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

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

With no output schema, the description usefully signals that the full body is returned rather than a stub. Parameters are fully covered by the schema. The one gap is that zero parameters are marked required, yet the tool needs either id or slug; the description says 'by id or by slug' but never states that one of them is mandatory.

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

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

Schema description coverage is 100%, so the id, slug, and projectId semantics (including the `post_...`/`prj_...` formats and the list_projects fallback) are already fully documented in the schema. The description's 'by id or by slug' only restates the lookup key choice at a high level, adding nothing beyond the schema baseline.

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

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

States a specific verb and resource ('Get a post') and adds scope: it returns 'one post with its full body,' which distinguishes it from list_posts and search_posts which return collections. It does not explicitly name those siblings, so it sits just below the top band.

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

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

The description gives no when-to-use guidance, no alternatives named, and no exclusions. The agent must infer that this is the single-record lookup versus the sibling list/search tools from the name alone.

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

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

Annotations already declare readOnlyHint/destructiveHint, yet the description adds substantial behavior beyond them: headless browser views are not counted, there is an ~1 minute rollup latency, dedup semantics (a reader counts once per post per day), and a required analytics.read grant. This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with what is returned, then usage procedure, then counting semantics, then the auth requirement. Every sentence carries information, though the tracking-verification sentence is somewhat run-on and could be tightened.

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

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

There is no output schema, so the description must describe the return, and it does (views, unique readers, clicks, per day). It also covers the auth requirement and timing caveats an agent needs before calling. Nothing material is missing.

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

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

Schema coverage is 100% and the schema already documents the from/to UTC-day patterns and their defaults plus the post_/prj_ id formats. The description adds only the 'per day' aggregation granularity, so it does not go beyond the structured fields. Baseline 3 applies.

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

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

Names the exact resource and metrics: views, unique readers and clicks for ONE post, per day. The scope ('one post, per day') implicitly separates it from the sibling get_content_analytics, which an agent can see covers aggregate content rather than a single post.

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

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

Gives a concrete when-to-use scenario ('check that a specific post's view landed after wiring up tracking') and the procedural preconditions (real browser, ~1 minute for rollup). It never explicitly names get_content_analytics as the alternative for broader queries, so routing between the two is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered without description help. The description adds a modest behavioral cue by enumerating returned content (identity, site, settings), but says nothing about permissions, scoping, or failure behavior for an unknown projectId. With annotations carrying the main burden, this is adequate-but-thin.

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

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

A single compact sentence fragment with no padding, and the key fact (one project) is front-loaded. It is efficient, though the terseness is arguably part of the under-specification rather than genuine conciseness.

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

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

There is no output schema, so the description carries the return-value burden; it partially discharges this by naming what a project contains (identity, site, settings). Still missing are the actual field-level shape, error behavior for invalid IDs, and differentiation from get_project_summary. Complete enough for a simple single-resource read, but shallow.

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

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

Schema description coverage is 100% and the single projectId parameter is fully documented in the schema, including the `prj_...` format. The description adds no additional meaning about the identifier, so the baseline 3 applies. Zero-ambiguity on a one-param tool keeps it from being a weak score.

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

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

The phrase 'One project' conveys singular retrieval of a project and lists contents (site, settings), so the resource is identifiable. However, it never names the retrieval verb or the identifier-based lookup semantics (by projectId), and it draws no boundary against get_project_summary or list_projects. The purpose is inferable but not sharply stated.

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

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

There is no when-to-use guidance at all. With siblings like list_projects, get_project_summary, and update_project in the same namespace, an agent gets no signal on when to pick this one over retrieving summary data or a full list. Only the implied 'single vs. many' distinction from the word 'One' offers any routing help.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that this is an aggregate single-call summary (counts, mode, traffic), which is meaningful context, but it says nothing about permissions, cost, or freshness/staleness of the traffic data.

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

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

Two tight sentences with the payload described up front and the usage rule second. No padding or restated information.

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

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

With no output schema, the description carries the burden of describing returns and does so by naming the four categories of data returned. Combined with annotations covering the read-only nature, an agent has enough to call it correctly, though it lacks detail on the shape of the traffic metric.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents projectId fully. The description adds no format or constraint detail beyond it, which is the correct baseline for a fully-documented single parameter.

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

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

States a specific verb and resource (get a summary for one project) and enumerates the exact contents returned: content counts, key count, database mode, recent traffic. It implicitly distinguishes from the list_* siblings by saying it replaces 'listing everything', but it does not explicitly differentiate from the close sibling get_project, so it falls just short of a 5.

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

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

Provides a clear when-to-use condition ('to answer "what is in here"') and names the alternative it replaces ('listing everything'). It does not state exclusions (e.g., when to prefer get_project or get_content_analytics instead), so it stops at 4.

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

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

Beyond the (consistent) readOnlyHint/destructiveHint annotations, the description discloses the real behavioral constraint: only names, creation dates and the last four characters come back, and a full key is shown once at creation and never again. It also states the required apikey.read grant, which the annotations do not cover.

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

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

Three tight sentences with no filler, front-loading what the tool returns and then the key-exposure rule and the grant requirement. Every sentence carries information the agent needs.

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

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

For a single-parameter list tool with no output schema, the description covers the salient risks (full keys never returned), the authorization requirement, and the shape of the returned fields, so nothing essential is missing.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already documents projectId as `prj_...`. The description adds nothing further about the parameter, making the baseline 3 appropriate.

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

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

The description states a specific resource (the read-only/website keys for this project) and what is returned (names, creation dates, last four characters). The listing verb comes from the title rather than the body text, and it does not explicitly name the contrasting sibling create_api_key, so it lands just below the top mark.

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

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

Usage is only implied: the tool returns existing keys, so an agent infers it is the read counterpart to create_api_key. There is no explicit statement of when to call this versus create_api_key, get_project, or any other sibling, and no prerequisites beyond the grant mention.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the results carry ids consumable by create_post, which is useful return-value context, but it says nothing about pagination behavior despite limit/cursor parameters existing.

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

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

A single tight sentence with no waste, and the most decision-relevant fact (these are the ids create_post needs) is placed at the end for emphasis. It is telegraphic but not padded.

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

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

For a simple read tool with no output schema, the definition covers what the resource is and why you'd want it, and annotations cover safety. It still leaves pagination semantics and the shape of returned entries (id plus name?) unaddressed, which matters given the undocumented limit/cursor params.

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

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

Schema description coverage is only 33% — projectId is documented in the schema, but limit and cursor are bare. The description's 'in this project' echoes projectId without adding format or default detail, and it never mentions that the list is paginated or what limit/cursor do.

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

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

The description identifies the resource (bylines/authors available in a project) and ties it to a concrete downstream use ('the ids create_post takes'), which distinguishes it from siblings like list_projects or list_tags. The verb 'list' is only implicit, but the noun phrase is specific enough that an agent knows what it returns.

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

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

It hints at when to reach for it — when you need author ids for create_post — which is a genuine usage cue. However it gives no guidance on alternatives (e.g. list_projects for the projectId, or create_author when no byline exists), so usage 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.

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

Annotations already establish this as a safe read (readOnlyHint=true, destructiveHint=false), so the description earns credit for adding genuinely new behavior: the ordering guarantee that a parent always precedes its children, and that counts are opt-in via include. It does not cover pagination or result size limits, which for a tree listing could matter.

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

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

Two compact sentences with the resource and its ordering contract front-loaded, followed by the one optional flag. No filler or restatement of the tool name.

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

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

With no output schema, the description carries the burden of describing the return shape, and it does so partially by explaining the tree ordering and the depth indentation. The `q` and `parentId` filters are left entirely to the schema, which is acceptable given their descriptions exist there, but pagination and empty-result behavior remain unaddressed.

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

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

Schema coverage is 75%, and the description fills the largest remaining hole: the schema's `include` property has no description, and the text explains it returns the number of posts per category. It also clarifies `depth` as an indentation value, though that appears to be an output field rather than an input, which could momentarily confuse an agent reading the schema.

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

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

The description names the resource precisely ('The category tree') and discloses its structural shape (parent precedes children), which is more than a tautology of the name. It does not, however, explicitly contrast itself with nearby siblings such as list_tags or list_authors, so an agent must infer the distinction.

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

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

Usage is implied by the resource name and the hint that include="counts" is an optional enrichment, but there is no statement of when to prefer this over list_tags/list_authors or of prerequisites. Adequate but with a clear gap in routing guidance.

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

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

Annotations already declare the safe read profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds real value beyond them: the sort order, the cursor-pagination contract, and the explicit 'no page number, by design' constraint, which prevents an agent from guessing an offset scheme.

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

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

Three short sentences, front-loaded with resource and ordering, then pagination and the filter-first rule. No sentence is wasted, though the 'by design' aside is slightly editorial rather than functional.

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

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

For an 8-param list tool with no output schema and annotations covering safety, the ordering and pagination contract are the key missing pieces and both are present. Returned field shape and default-filter behavior remain unstated but are minor for a read-only list.

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

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

Schema description coverage is 75%, so the schema documents most parameters itself. The description only reinforces the cursor parameter ('from the previous response') without adding syntax or semantics the schema lacks, so the baseline 3 applies.

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

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

States the resource ('Posts in a project') and the ordering ('newest published first'), which is a clear, specific list operation. It does not name the sibling it is not (search_posts), so differentiation from closely related list/search tools is left to the schema, not the description.

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

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

Provides procedural guidance ('Paginate with cursor', 'Filter before paginating') but never states when to choose this over search_posts or get_post. Usage is implied rather than routed, so an agent must infer the boundary from the schema.

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

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

Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false), so the safety burden is lifted. The description usefully adds the workspace scoping and the id format for chaining, but says nothing about result ordering, pagination, or completeness limits for a workspace with many projects.

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

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

A single compact clause that front-loads the scope and tucks the id-format detail where it matters. Nothing wasted, nothing padded.

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

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

For a zero-parameter list tool with no output schema, the description tells the agent what comes back (all projects in the token's workspace) and the shape of the ids. Missing only ordering/pagination behavior, which is minor at this complexity.

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

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

Zero parameters and 100% schema coverage, so the baseline is 4. There are no parameters whose meaning the description could clarify, and nothing is misdescribed.

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

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

States the resource (projects) and scope (every project in this token's workspace), which separates it from get_project and the other list_* siblings. It never uses an explicit list verb, but the enumerating quantifier 'Every project' makes the operation unambiguous.

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

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

Usage is only implied: by promising the `prj_...` ids the content tools take, it hints you call this first to discover project ids. There is no explicit when-to-use, when-not-to-use, or named alternative such as get_project for a single project.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds that results are enriched with per-tag post counts, a behavior beyond the annotations. However, it says nothing about pagination, result ordering, or whether soft-deleted tags appear, which matters for a list endpoint with limit/cursor.

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

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

A single tight sentence with zero filler, and the resource is front-loaded ahead of the detail. It is arguably too terse to function as a sentence, but nothing is wasted and nothing dilutes the key information.

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

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

There is no output schema, so the description carries the return-shape burden, and it does partially discharge that by naming the post-count field. But a paginated list tool should also describe paging behavior and the cap on limit; those omissions leave the definition only adequate.

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

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

Schema description coverage is only 33% — only projectId is documented, while limit and cursor are bare. The description says nothing about pagination, cursoring, or the maximum limit, so it does not compensate for the schema gap. An agent gets no help on how to page through results.

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

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

The description states the resource (tags in a project) and adds a meaningful detail about the payload — each tag comes with its post count. That makes the tool distinguishable from create_tag or list_categories. The verb is only implied by the name, so it's clear but not maximally explicit.

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

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

There is no guidance on when to call this versus alternatives such as list_categories (sibling for the other taxonomy) or create_tag. No prerequisites, ordering, or exclusion conditions are stated. The agent must infer usage purely from the name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered by structured data. The description goes beyond that by disclosing an entitlement caveat ('May require a paid capability on the workspace') and noting results are ranked, which is genuinely useful operational context; it stops short of describing pagination or empty-result behavior.

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

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

Three short clauses, each load-bearing: what it does, which sibling to prefer, and the entitlement caveat. No filler and nothing important buried.

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

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

No output schema exists, yet the description says nothing about the shape of results beyond 'ranked' — no mention of pagination, total counts, or what happens when nothing matches. The paid-capability warning partially offsets this, but the result contract remains underspecified for a search tool.

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

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

Schema description coverage is only 25% (only projectId is documented), so the description must compensate — and it adds nothing about q, limit, or status. The enum for status and the numeric bounds for limit are self-evident from the schema, but q's matching behavior and limit's pagination role are unexplained in either place.

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

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

States a specific verb and resource with scope ('Full-text search across titles and bodies, ranked'), and explicitly separates itself from the sibling it could be confused with ('use list_posts to enumerate'). An agent can choose between search_posts and list_posts without opening either schema.

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

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

Gives both the positive condition ('Use this to find something') and the alternative with its own condition ('use list_posts to enumerate'). This is explicit when-to-use/when-to-use-something-else guidance, not implied.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real extra weight by disclosing the cascade effect ('moves everything beneath it too') and the cycle guard ('cannot be moved inside one of its own subcategories'). It does not say what happens to unspecified fields or whether the operation is atomic, but the disclosed traits are genuinely useful and non-obvious.

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

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

Two sentences, both front-loaded with the most consequential information (what it does, then the cascade caveat). Nothing is redundant and no filler is present.

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

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

There is no output schema and only 50% parameter coverage, so the description should do more. It covers the rename/move semantics and the key constraint, but is silent on slug/description updates and on outcomes such as what is returned or what happens on a failed move.

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

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

Schema coverage is 50%: id, parentId, and projectId have descriptions, while name, slug, and description do not. The description maps loosely onto name (rename) and parentId (move), but it never mentions updating slug or description, so an agent could easily overlook two of the tool's mutable fields.

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

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

States a specific verb and resource ('Renames a category, or moves it under a different parent'), clearly separating it from siblings like create_category, delete_category, and list_categories. However, it frames the tool only as rename/move, while the schema shows slug and description are also updatable, so the stated purpose is narrower than the tool's actual scope.

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

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

Usage is implied by the verb phrase (rename or reparent an existing category), and the sibling set makes the create/delete/list boundary fairly inferable. But there is no explicit when-to-use guidance, no statement of prerequisites, and no named alternative for the adjacent operations.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses high-value behavioral traits: partial-update semantics (omitted fields untouched), an elevated permission requirement for publishing, optimistic-concurrency behavior (REVISION_CONFLICT), and the recovery workflow (re-read and reapply). This is exactly the extra context annotations cannot convey.

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

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

Three tightly packed sentences, front-loaded with the most important fact (partial update), then publishing, then concurrency safety. No filler; every sentence earns its place.

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

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

For a 15-parameter mutation tool with nested objects and no output schema, the description covers the critical path (partial update, publish, concurrency). Gaps remain around scheduling/status transitions and how tags replacement or authorId reassignment behave, but the core call path is well supported.

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

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

Schema description coverage is only 33%, so the description must carry more weight. It does explain the two most consequential parameters (status's publish semantics and expectedRevision sourced from get_post), but the remaining 13 parameters (seo sub-fields, tags, bodyFormat, scheduling fields, authorId) are left to the schema alone.

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

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

The description states a specific mutation with precise patch semantics: 'Changes only the fields you send; anything omitted is left alone.' Combined with the name/title (update_post), an agent knows exactly what the tool does. It does not, however, explicitly distinguish itself from siblings like create_post 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.

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

It gives concrete usage context: publishing happens here via status "published", which requires the content.publish grant, and expectedRevision should be passed to guard against stale writes. It stops short of explicit when-not-to-use guidance or naming an alternative sibling for a given scenario.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, both generic; the description adds the critical behavioral facts — that allowedOrigins REPLACES rather than merges the list, how to format the values, and the required project.write grant. Disclosing overwrite semantics that could silently drop origins is exactly the context annotations cannot carry.

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

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

Front-loaded with the purpose, then the merge rule, then the high-risk allowedOrigins caveat — a sensible order with no filler. The sentence explaining what origins control is useful but slightly expendable, keeping it out of 5 territory.

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

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

For a 6-parameter mutation tool with no output schema and half the parameters undocumented, the description still covers purpose, merge behavior, the risky field, and auth. Minor gaps remain: it never says null clears name/description, nor how errors on the required projectId are surfaced, but nothing essential to a correct call is missing.

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

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

With only 50% schema coverage, the description compensates well for the most dangerous parameter, giving format, example values, an explicit "pass every origin" rule, and a note that it governs browser use of the project key. It adds little for websiteUrl vs websiteName, though the schema already annotates websiteUrl as display-only.

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

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

States a specific verb (Change) plus the resource (a project) and enumerates the mutable fields (name, description, website, allowed origins). An agent can distinguish it from create_project and get_project without opening any schema.

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

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

"Only the fields passed change" establishes partial-update semantics and "Requires the project.write grant" gives a precondition, which is clear usage context. It does not explicitly name a sibling alternative or a when-not-to-use case, 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.

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

Annotations only establish readOnlyHint/destructiveHint, but the description goes well beyond them: it explains the distinction between agentGrants (token capability) and permissions (owner capability), states that a tool works only when both allow it, and gives a conditional action for mcp.outdated (warn the user before filing a bug). That is substantive operational context an agent could not infer from structured fields.

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

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

Front-loaded with what the tool is and the call-first directive, then earns each remaining sentence with distinct information. It is dense and slightly long, but no sentence is filler.

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

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

There is no output schema, so the description carries the burden of explaining return values — and it does, covering agentGrants, permissions, and the mcp object including the outdated flag. Nothing material is left for the agent to guess.

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

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

The tool takes zero parameters, so the baseline is 4. The description instead spends its budget on the semantics of the returned fields, which is the right call and more valuable than parameter prose would be.

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

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

The description names a specific resource and scope: 'the account this token acts as and the workspaces it can see.' That is unmistakably distinct from every sibling (projects, posts, categories, keys), none of which report token identity.

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

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

It gives an explicit sequencing rule — 'Call this first in a new conversation' — plus a rationale (confirms the token works and names the workspace). There is no when-not or named alternative, but no sibling serves as a substitute for identity discovery, so the guidance is effectively complete.

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