COTAL actions (cotal.ai)

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

Beyond the annotations (which only flag non-readOnly, non-idempotent, non-destructive), it discloses the gated lifecycle and that a human must publish, plus the auth requirement of a team key. It omits whether a repeated call with the same slug collides or duplicates, which matters for a non-idempotent write.

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 the action and destination, then lifecycle and return value, then the auth prerequisite. No filler or restated name/title.

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

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

Covers what it creates, the approval gate, the return values (slug and preview URL) even without an output schema, and the credential requirement. The remaining gap is collision/idempotency behavior for slug reuse, minor for a staging 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 100%, so every parameter including the status enum is already documented. The description's note about draft vs pending restates the schema's own explanation rather than adding new meaning (allowed values, defaults, tag constraints), so 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 ('Stages a new article for the Cotal build log') and anchors it with the destination site. The staging framing implicitly separates it from cotal_update_post and the get/list siblings, though no sibling is named.

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?

Explains the draft-vs-pending decision directly in terms of consequence ('lands as a draft unless you submit it for review... goes live only after a human publishes it'), which is exactly the choice an agent must make. It doesn't explicitly say to use cotal_update_post for existing articles instead, so the alternative path is left 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds value beyond them by describing the payload (all fields, current markdown, revision history) and disclosing an auth requirement (team key), which no annotation conveys. It stops short of noting pagination or size limits, but this is a reasonable disclosure level.

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

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

A single front-loaded sentence with semicolon-separated clauses: payload first, then the revision rule, then the auth caveat. Every clause carries information, though the packed structure is slightly dense for a one-sentence definition.

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 must carry return-value information, and it does: every field, current markdown, and revision history. Combined with the stated team-key requirement and revision behavior, an agent has enough to call this correctly; only pagination/error behavior is 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 description coverage is 100%, so the schema already documents both slug and revision, making 3 the baseline. The description adds only mild nuance via 'pass revision for an older text', and arguably understates the schema's wording that revision text is returned in addition to the current text.

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 ('one staged article') and enumerates what comes back (every field, markdown, revision history), so an agent knows this is a single-item read rather than a list. It does not explicitly contrast with the similarly named sibling cotal_get_post, leaving the staged-vs-published distinction to inference from the tool name's 'my'.

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 one concrete usage rule ('pass revision for an older text') and an auth prerequisite ('Requires a team key'), which is genuine guidance. However it never states when to pick this over cotal_get_post or cotal_list_my_posts, so the sibling routing is only implied by 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 readOnly=true, idempotent=true, and destructive=false. The description adds that it returns markdown content with specific fields (title, summary, date, author, full body), which provides context about the output behavior without contradicting the annotations. No side effects are implied, consistent with annotations.

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

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

The description is two sentences with no redundancy. It states the purpose, the output format, and how to obtain the slug, all efficiently. No unnecessary words or ambiguity.

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 get-by-slug tool with a single parameter, the description is complete. It tells what it returns, how to get the slug, and the output format. No output schema is provided, but the description sufficiently describes the return value. Given the simplicity, 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?

The schema fully covers the parameter with minLength, maxLength, and a description. The description adds a concrete example ('agi-summit-2026') that clarifies the expected format, which is helpful beyond the schema. Coverage is high, so the baseline is 3, but the example earns a 4.

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

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

The description clearly states it returns a single build-log post by slug, distinguishing it from list_posts (which likely lists all posts) and search (which finds posts). The verb 'returns' and the specific resource 'post' make 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.

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

The description explicitly instructs to get slugs from cotal_list_posts or cotal_search, indicating when to use this tool after obtaining a slug. However, it does not explicitly state when not to use alternatives, such as 'use this instead of list_posts when you need full details of one post.' Still, the guidance is clear enough.

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

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

Annotations already provide idempotentHint=true, and the description adds valuable detail beyond that by explaining the exact idempotent behavior: 'calling again updates the optional details instead of adding a second seat.' This enriches the annotation with practical context. It also notes the closure status (closed alpha) which sets expectations. No contradictions.

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

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

The description is just two sentences with zero fluff. The first sentence delivers the core action, and the second delivers the key behavioral nuance (idempotency). It is front-loaded and every word earns its place.

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

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

The description is complete for the primary use case. It explains what the tool does and its idempotent behavior, and the schema covers all parameters. With no output schema and simple parameters, it doesn't need to describe return values or error handling. Minor gap: no mention of what happens if the email is invalid, but that's schema's role, so this is sufficient.

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

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

Schema description coverage is 100%, and each parameter already has a clear description. The tool description doesn't add extra meaning beyond the schema—it only mentions 'user's email' generically, which is already in the schema. The baseline of 3 applies since the schema handles parameter semantics fully.

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

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

The description clearly states the specific action ('Reserves a seat on the waitlist for Cotal Cloud') with a clear verb and resource. It also identifies the scope (user's email) and the product context (closed alpha), making it unambiguous and distinct from sibling tools like cotal_subscribe_newsletter or cotal_request_call.

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

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

The description provides clear context for when to use the tool: when a user wants to join the Cotal Cloud waitlist. It doesn't explicitly name alternative tools or exclusion conditions, but the purpose is self-evident and distinct. This is slightly above baseline but not a 5 because there is no explicit 'use when' or 'instead of' 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds context the annotations do not: the authorization requirement ('Requires a team key') and the shape of what is returned, which is valuable given there is no output schema.

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 efficient sentence with no filler, using a compact colon-delimited field list. It is slightly back-loaded in intent, opening with a noun phrase about return content rather than the action verb, but nothing is wasted.

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

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

For a read-only listing tool whose safety profile is fully covered by annotations and whose two parameters are fully documented in the schema, the description supplies the missing pieces: listed fields and the team-key requirement. Only secondary details such as pagination, sorting, or result limits are 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%, so both parameters (slug, status) are already fully documented by the schema, and the enum values listed in the description merely restate the schema's enum. No additional filter semantics or combination behavior is added, so 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?

The description clearly states the resource and scope: the review state of articles staged on this site, with an explicit field list (slug, title, status, review note, revision). It never explicitly distinguishes itself from siblings like cotal_list_posts (all posts) or cotal_get_my_post (a single post), so an agent must infer the 'my/staged' scope from the name alone.

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 name and the stated prerequisite 'Requires a team key,' which tells the agent a precondition for calling it. However, there is no guidance on when to choose this over cotal_list_posts or cotal_get_my_post, and no when-not condition or alternative 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?

The annotations already establish readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context beyond the annotations: newest-first ordering, cursor pagination, and the fields returned for each item, which helps the agent understand what a call will produce.

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 tightly written sentences with no wasted language. The core purpose and ordering are front-loaded, followed immediately by the pagination mechanism and return shape.

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

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

Because there is no output schema, the description correctly compensates by naming the item fields (slug, title, summary, date, author, URLs) and explaining pagination. It could be slightly more complete by clarifying end-of-list behavior or whether next_cursor can be absent, but for a simple read-only list tool it covers the essentials.

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 both parameters are already documented in the input schema. The description reinforces cursor reuse via next_cursor and explains the ordering and returned item fields, but it adds little parameter-level meaning beyond what the schema already provides, 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 verb and resource: it lists posts from the Cotal build log, newest first, with cursor pagination. That is clearer than a generic list tool, but it never explicitly contrasts itself with close siblings such as cotal_list_my_posts or cotal_search, so an agent must infer the difference from the name alone.

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 scope (browse the public build log) and by the instruction to pass next_cursor for the next page. There is no explicit when-to-use or when-not-to-use guidance, and no mention of when cotal_list_my_posts or cotal_search would be better choices.

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, idempotentHint=true, and openWorldHint=false, so the safety profile is covered by structured data. The description adds useful non-annotation context: that the payload is structured and sectioned, and that it should be the first call in an onboarding flow. It doesn't mention static/cached nature or freshness of the content, 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.

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

Three sentences, front-loaded with the return payload, then the when-to-call rule, then the parameter note. The mid-sentence content enumeration is long but each item is a distinct sub-topic an agent might need, so it earns its place; slightly tighter phrasing would reach 5.

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 the description compensates by enumerating the return contents and the available sections, so an agent knows what it will get back. Combined with the entry-point guidance and the annotation safety profile, nothing needed to invoke this single-optional-parameter tool 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?

Schema coverage is 100% and the enum's seven values are fully documented in the schema, so the schema does the heavy lifting. The description adds only the default behavior implied by 'Pass `section` to get one part only', which the schema also states ('default: all'). 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?

The description names a specific verb ('Returns a structured overview') and resource (Cotal), then enumerates exactly what that overview contains: what it is, who it's for, when to use it, install, API/MCP surface, pricing, and links. None of the sibling tools (get_post, list_posts, search, join_waitlist, etc.) do this, and the enumeration makes that distinction obvious 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?

'Call this first when a user asks what cotal.ai does' gives an explicit trigger and sequencing rule, which is genuinely useful for orienting an agent among twelve action-oriented siblings. It stops short of naming alternatives or exclusions (e.g., when to prefer cotal_search for a specific query), so it isn't a full when/when-not statement.

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 is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds genuine value beyond that by disclosing the response channel ('The team replies by email'), which matters because there is no output schema, and by flagging the two required identity fields. It omits the existence of a dry-run mode (sandbox) and of retry-safe behavior via idempotency_key, both of which shape how the agent should call it.

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 action front-loaded and the outcome second; nothing is padded. The final clause about required email and company is somewhat redundant with the schema's required array, costing a perfect score.

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 9-parameter write tool with no output schema, the description covers what happens (a request is sent), who receives it, and how the sender hears back — the key information the schema cannot convey. The remaining gaps (sandbox dry-run semantics, idempotent retry behavior, rate limits) are documented in the parameter descriptions themselves.

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 nine parameters (including sandbox, idempotency_key, agents enum) are already documented in the schema. The description only restates that email and company are required, adding no syntax, format, or defaulting information beyond the schema. 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 ('Sends a discovery-call request to the Cotal founders') plus the target audience, which separates it from contact-free siblings like cotal_join_waitlist or cotal_subscribe_newsletter. It does not name an alternative sibling explicitly, keeping it just below 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?

The phrase 'for a company evaluating agent coordination' implies the audience, but there is no explicit when-to-use/when-not guidance and no pointer to sibling routes such as cotal_join_waitlist or cotal_submit_feedback for users who are not ready for a call.

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 readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description meaningfully adds that matching is keyword-based and that results are ranked with canonical and markdown URLs, which tells the agent what shape of answer to expect.

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

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

Three short sentences with nothing wasted: scope first, return shape second, usage cue last. Every sentence earns its place and the scope is front-loaded.

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

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

There is no output schema, and the description compensates by describing the return payload (ranked results with canonical and markdown URLs). It stops short of noting result limits behavior or whether matching is strict, but nothing essential for calling the tool 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% – query examples, min/max length, and the limit default and ceiling are all documented in the schema. The description adds no extra guidance on query formulation or result-count selection, 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 (keyword search) plus the exact corpora it covers: the build log/blog posts and key documentation and site pages. That distinguishes it from cotal_list_posts and cotal_get_post in substance, though no sibling is named explicitly.

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?

"Use it to find the page that answers a question before reading it" gives a clear workflow cue, implying a follow-up read via cotal_get_post. It does not state exclusions (e.g., when to prefer cotal_list_posts for browsing) or note that it is keyword rather than semantic matching.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: it is the same log the site's feedback widget writes to, and the email is needed for follow-up. It says nothing about rate limits (only the sandbox param hints at them) or about the sandbox dry-run mode, which would be valuable 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.

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

Three short sentences, front-loaded with the core action, and each sentence carries distinct information (action, destination, prerequisite). Efficient, though the email sentence could be folded into the first without loss.

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?

Ten parameters with three required and no output schema, but the schema is fully documented, so the description needn't restate field semantics. The main omission is the sandbox dry-run and retry/idempotency behavior, which matter for an agent calling a write tool that submits content off-platform.

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 schema already documents all ten parameters including enums and the idempotency key. The description adds minor meaning by naming the feedback type categories and the purpose of email, but does not compensate with anything the schema lacks. Baseline 3 is appropriate.

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

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

States a specific verb (files) and resource (feedback) with the enumerated types and the recipient (the Cotal team on behalf of the user). No sibling tool handles feedback, so an agent can route here 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?

Usage is only implied: the agent must infer that this is for when the user has a bug/idea/friction to report. The precondition that the user's email is required is stated, but there is no when-not guidance and no mention of alternatives such as cotal_request_call or cotal_draft_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 idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the restated no-op behavior partly duplicates structured data. It adds no information on authentication expectations, whether the user is confirmed/consenting, or what a successful 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?

Two short sentences, zero filler, with the core action front-loaded and the idempotency caveat as the second beat. Nothing could be removed without losing meaning.

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

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

For a low-complexity two-parameter tool with no output schema and complete schema coverage, the description plus annotations cover action, scope, and repetition behavior adequately. A brief note on the success response and whose account is subscribed would close the remaining gap.

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

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

Schema description coverage is 100%, and both the email format and the sandbox dry-run flag are fully documented in the schema, including the rate-limit-validate-store-nothing semantics. The description adds nothing beyond that, so 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 ('Subscribes the user's email to release updates from the Cotal team'), so intent is unmistakable. It does not differentiate from the nearest sibling, cotal_join_waitlist, which is a related but distinct signup path.

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

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

The phrase 'release updates from the Cotal team' implies when the tool applies, but there is no explicit when-to-use or when-not guidance, and no pointer to cotal_join_waitlist for the adjacent signup case. Usage must be inferred from the name and scope.

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?

Adds substantial behavior beyond the annotations: no-op-on-identical-text semantics (consistent with idempotentHint=true), 409 refusal when base_revision is stale, the rule that published posts keep their live text until a human publishes the revision, and the team-key auth requirement. That is exactly the non-obvious context an agent needs before calling.

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

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

Five short sentences, front-loaded with what the tool does, then the revision semantics, then concurrency, then publish behavior, then the auth requirement. 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?

For a 10-parameter mutation tool with no output schema, it covers the important behavioral surface: idempotency, concurrency conflict, publish/revise split, and permission requirements. It leaves the restore and new_slug (rename) semantics unexplained, though those are partly covered by the schema descriptions.

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 70%, so most parameters already carry descriptions; the description reinforces base_revision's conflict role and clarifies that title/dek/body changes create a revision. It adds nothing for dek, tag, title, or the non-obvious restore/new_slug behaviors, so it neither fully compensates nor falls short of 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 ('Improves an article staged with cotal_draft_post') and anchors itself to the sibling that creates the artifact, so an agent can place it correctly relative to cotal_draft_post and the read tools without opening a 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 real usage conditions: it operates on posts already staged via cotal_draft_post, it no-ops when the text is unchanged, and it names base_revision as the guard for concurrent edits. It stops short of explicitly naming when to use a different sibling for a given need, but the scope is clear.

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