Seovyn

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. The description adds useful provenance context ('read from the server's own routes'), implying live/authoritative data rather than a static list, but says nothing about result volume, truncation, or pagination for what is potentially a very large listing.

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 packed sentences: the first defines the resource and its contents, the second routes the agent to the sibling tool and explains the filter. Zero filler and the most decision-relevant information (what it returns, when to use it) 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?

For a low-complexity, single-parameter reference listing with no output schema, the description covers what comes back and how to filter it. The only omission is guidance on result size or whether the endpoint list is returned in full, which matters given the breadth implied by 'every endpoint.'

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

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

Schema coverage is 0% and the lone `search` parameter has no schema description, so the description carries the burden — and it does: 'a word in the path or description' tells the agent exactly what the filter matches. It stops short of noting case sensitivity or partial-match behavior.

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 resource (every Seovyn API endpoint) and what the payload contains (method, path, what it does), plus the source (the server's own routes). An agent can distinguish this discovery tool from named siblings like seovyn_status or seovyn_whoami 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?

Explicitly names the companion tool (seovyn_api_request) and the condition that selects this one: 'anything the named tools don't cover.' It also tells the agent how to narrow results via `search`, so both when-to-use and how-to-use are covered.

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

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

Discloses the two-step write protocol that annotations only hint at: non-GET methods return a preview and only execute with confirm: true, and confirm should be set only after user agreement. It also describes the return shape ('the API's own status and data'). This goes well beyond readOnlyHint=false / destructiveHint=true.

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 clauses: what it is, the call shape, and the GET-vs-mutation rule with confirmation. Front-loaded and free of 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 complex, destructive, no-output-schema gateway tool, the description covers invocation, the confirm safety flow, and the return nature. The only minor gap is that the org parameter's scoping behavior is left entirely to 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 coverage is 50% (org, path, confirm documented; method, query, body not). The description adds value by showing the request shape { method, path like "/content/items/<itemId>", query?, body? } and marking query/body optional, but leaves the body/query contents and method semantics to the reference doc.

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: 'Call any Seovyn API endpoint as the user, in one organization', and immediately points to seovyn_api_reference for the catalog the tool wraps. An agent can tell this is the generic escape hatch, distinct from the specific siblings like seovyn_brand or seovyn_get_article.

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 clear context: consult seovyn_api_reference to pick an endpoint, GET runs immediately, everything else is preview-then-confirm. It doesn't, however, say when to prefer a purpose-built sibling over a raw API call, which is the main selection decision for this 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?

With only readOnlyHint=false and destructiveHint=false provided, the description carries real weight and delivers: it explains the approval-streak gating, that autopilot publishes on its own after a hold, that turn_off resets the streak, and that turn_off requires confirmation. It does not state permission/authorization requirements, but the side-effect profile is otherwise well disclosed and consistent with the annotations.

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

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

Front-loaded with the core concept ("The autopilot") before drilling into actions, and every clause carries information. The multi-clause semicolon sentences are dense and slightly harder to parse than ideal, but there is little true 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 sensibly describes what status returns (mode, last 20 decisions vs. autopilot's hypothetical choices, recent events, publishing pace). For a 5-parameter, 0-required mode-control tool the coverage is solid; only auth/permission context 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?

At 60% schema coverage, the description compensates meaningfully: it defines the semantics of each enum action (which the schema leaves undocumented) and adds the 1-36 range plus 'null for no pacing' for maxArticlesPerDay. The org and limit parameters are left to the schema, which already documents them, so only partial compensation is needed.

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 and behavior: autopilot mode management, with three named actions and an explicit default ("status"). It clearly frames the supervised-vs-autopilot distinction, though it never names or routes against siblings like seovyn_publish_queue or seovyn_review_article that an agent might confuse with publishing control.

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?

Each action is given a clear context: status is the default and returns mode/decisions/events/pace, set_pace controls daily volume, turn_off reverts to supervised and "needs confirm." The confirm-parameter workflow (set true only after reviewing the preview) is spelled out. No explicit when-not or alternative-tool guidance is given, so it stops short of the top band.

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, consistent with the get/update/set_niche actions. The description adds that 'update' accepts 'any of' the fields, implying partial rather than full-replacement updates, which is useful. It does not disclose whether omitted fields are preserved, what get returns, or any auth/org-resolution behavior beyond the schema's org note.

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

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

It is a single dense block but front-loads the resource definition and then the action mapping, so no sentence is wasted. Structure is compressed (semicolon-chained) but appropriate for a descriptor of this scope.

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 tool with 7% schema coverage and no output schema, the description covers the parameter-to-action mapping well but never states what 'get' returns or the response shape. org is delegated to the schema, so coverage is adequate but not fully complete for a tool this complex.

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 7% (just 'org'), so the description must compensate and largely does: it maps fields to the update action and supplies enum values the schema lacks for tone (practical | authoritative | friendly | technical) and pointOfView (we | i | neutral), plus the '2 letters' constraint for country and array types for bannedPhrases/mustMention. Remaining fields like org are left to 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 opening sentence identifies the resource ('the brand profile every article is written to') and the description then enumerates the three operations (get/update/set_niche), so an agent understands it manages brand-profile configuration. The verb is implicit rather than stated as a clean verb+resource, but the multi-action scope 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?

For a multi-mode tool, the description explicitly delineates the modes: get is the default, update applies with the listed fields, and set_niche takes a niche sentence. That is clear routing guidance between actions, though it never names conditions for choosing this tool over siblings like seovyn_write_article.

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?

With destructiveHint=true already declared, the description goes well beyond the annotation by spelling out the actual consequences: unpublish 'takes the page down' and noindex 'hides it from Google', both restricted to 'Seovyn-hosted sites only', and both requiring confirm. That is exactly the destructive-effect detail an agent needs before acting.

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?

Compact and front-loaded: scope first, then each action inline. The nested quoting around 'decide' { itemId, decision: keep | unpublish | noindex } is dense but each clause earns its place; no filler sentences.

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

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

For a 5-param, no-output-schema, destructive tool the description covers scope, all three actions, decision semantics, the confirm gate, and the hosted-site restriction. Remaining gaps (org defaulting, what the list/review output looks like) are minor and partly covered by 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 coverage is 60% and the enums for action/decision carry no schema descriptions, so the description does real work by defining each action's behavior and each decision value's effect. Only 'org' is left to the schema, which documents it adequately.

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 as 'live articles that need a decision (thin, overlapping or not earning)' and enumerates the three actions, so an agent knows this is a triage/cleanup surface rather than a general article listing. It does not explicitly name the close siblings (seovyn_list_articles, seovyn_review_article) to draw the boundary, which keeps it at 4.

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?

Per-action guidance is explicit: 'list' is the default, 'review' is for looking over live articles now 'instead of waiting for the weekly pass', and 'decide' is for recording a decision. What's missing is any statement of when to prefer this tool over the sibling list/review tools.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is already covered. The description adds some context about the returned data (traffic, sitemap sections, topic coverage), but does not describe return format, pagination, or any limitations.

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

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

The description is a single, compact sentence with no wasted words, and the key data points are front-loaded. However, it is a sentence fragment rather than a complete clause, which slightly reduces structural clarity.

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 one optional parameter and no output schema, the description gives a reasonable hint at the returned data but does not fully explain the output shape or scope (e.g., number of pages, grouping). It is minimally adequate but leaves 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 100% for the single optional 'org' parameter, with the schema itself explaining that it accepts an accountId, website, or name and defaults to the current organization. The description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description is a noun phrase listing the data returned (competitor best pages by traffic, sitemap sections, topic coverage) rather than a verb+resource statement of what the tool does. It is specific about content and distinct from siblings, but lacks an action verb to make the purpose immediately obvious.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description only states what data is returned, leaving the agent to infer the context from the name and sibling list.

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

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

Beyond the annotations it discloses real side effects: Seovyn reads the site, plans first keywords, and makes the new org the dashboard's current organization. 'Can't be undone from here: needs confirm' adds the irreversibility and approval-loop context that readOnlyHint=false alone does not convey, though it sits slightly awkwardly against destructiveHint=false.

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?

Dense but purposeful: mode one, mode two, side effects, then the confirm warning in that order. Sentence fragments cost some readability but no line 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 6-parameter creation tool with no output schema, the description covers the two input shapes, the downstream effects, the confirm gate, and the permanence warning. The remaining gap is an unclear name-versus-businessName distinction in the no-website branch.

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 33%, and the description compensates partially by grouping fields into the two creation modes. However, it never distinguishes 'name' from 'businessName' or says what 'description' should contain beyond implying it feeds site building, leaving the highest-risk fields under-specified.

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 conveys a specific resource (a new organization tied to a website) and lays out the two creation modes with their field shapes. The verb 'create' is only implied by 'A new organization', but an agent can still tell this apart from every sibling, none of which create orgs.

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 explicitly says which mode to use for which situation: {name, website} for an existing site versus {name, noWebsite, businessName, description} for a business without one. It also states the confirm requirement, so the preview-then-confirm sequence is clear; what is missing is any routing versus siblings.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the edits apply to drafts only, and 'the quality checks run again on the saved version' tells the agent edits trigger re-validation. It omits partial-vs-full update semantics (are omitted fields preserved?) and any error behavior for non-draft items.

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, front-loaded with the action and scope, then field list, then the re-validation note. Dense and waste-free; the '(drafts only)' parenthetical slightly repeats 'before it is approved' but adds emphasis rather than noise.

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 mutation with no output schema and no annotation coverage for anything but safety, the description covers the input side well but leaves the response unclear (what does a successful edit return, and are quality-check results surfaced?). Partial-update behavior and non-draft error handling are also 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 only 22%, so the description carries the load — and it does, naming the seven editable fields and adding constraints the schema lacks: body is Markdown, metaTitle ≤70, metaDescription ≤170, tags ≤6. It does not clarify that omitted fields are left unchanged versus cleared, which matters for a 9-parameter mutation.

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 (Edit) and resource (a draft / article) and pins the scope with 'drafts only' and 'before it is approved', which implicitly separates it from creation (seovyn_write_article) and review (seovyn_review_article). It does not name a sibling outright, so the distinction still requires the agent to infer from the other descriptions.

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?

'Edit a draft before it is approved (drafts only)' gives a clear condition for when the tool applies and implicitly excludes published/approved articles. It does not name an alternative tool or say what to do if the item is already approved, so no exclusions/routing are spelled out.

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. The description goes beyond that by disclosing the actual return surface, including the body as Markdown, the quality verdict, and what autopilot would do with the article — genuinely useful context with no output schema to carry 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?

A single front-loaded sentence that leads with the core fact ('One article in full') before the field enumeration. The list is long but each item earns its place, since there is no output schema to describe the payload.

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 read tool with no output schema, the description covers the essential retrieval question and enumerates the returned fields well enough for an agent to know what it gets back. Minor gaps: no mention of not-found behavior or of the autopilot 'what it would do' being hypothetical.

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 are documented in-schema (itemId provenance, org fallback to the current org). The description adds nothing about parameter meaning, which is the correct baseline when the schema does the heavy lifting.

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 article in full' unmistakably identifies a single-resource retrieval, and the enumerated payload (body, title, slug, meta, tags, keyword, research, verdict, autopilot stance) distinguishes it from the sibling seovyn_list_articles. It stops just short of 5 because it never states an explicit verb like 'fetch' or 'retrieve'.

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: nothing says this is the read path for a single article versus seovyn_list_articles, seovyn_review_article, or seovyn_edit_article. The only routing hint ('itemId from seovyn_list_articles') lives in the schema, not the description.

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 state readOnlyHint=false and destructiveHint=false. The description adds real behavioral context beyond them: 'change' rewrites pages and puts them live, and requires a preview-then-confirm step. That the live-publish consequence is disclosed is valuable for a mutation action.

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 dense sentence front-loads the resource definition and then walks the action modes in order, with the confirmation caveat attached to 'change'. It is information-rich with little waste, though slightly packed.

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 and 4 params, the description covers the mutation flow and confirmation requirement adequately. It is a bit thin on what 'enquiries' returns and on org-scoping behavior, but nothing essential to invoking 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?

Schema coverage is 50%: 'org' and 'confirm' are documented in-schema while 'action' and 'instruction' are not. The description compensates by explaining the enum values in detail and the meaning of 'instruction' for the change action, adding meaning beyond the bare 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 specific resource (the site Seovyn hosts for a business without its own website) and enumerates the three action modes with concrete outcomes. An agent can tell it manages a hosted site, but it never names or contrasts any sibling tool to disambiguate.

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 maps each action to its use case ('get' default, 'change' for rewrites, 'enquiries' for contact-form messages) and flags that 'change' needs confirmation. It gives clear operational context but offers no exclusions or named alternatives among the many siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description meaningfully adds that connecting an integration requires credentials and steers that write action to the dashboard or seovyn_api_request. This extra auth/routing context goes beyond what the annotations convey and is consistent with the read-only hint.

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 opening is a rambling run-on sentence that crams publishing destinations, state, Google Search Console, site platform, and destination-matching into one clause chain without a leading verb. It is not front-loaded and reads more like a concept gloss than a tool 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?

For a read-only listing tool with one optional, fully documented parameter and no output schema, the description covers what information appears but muddles the tool's actual action. Without annotations carrying the full burden it is borderline adequate rather than complete.

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

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

Schema description coverage is 100% and the single `org` parameter is fully documented in the schema, including how to discover values via seovyn_whoami. The description adds no parameter meaning beyond that, 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?

The description enumerates the resource (publishing integrations) and what each carries — destination, state, Google Search Console, site platform — but never states a clear verb for what the tool itself does (list? inspect?). An agent can infer it surfaces integrations, yet the action is left implicit rather than declared.

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 useful routing exclusion — connecting requires credentials and should be done in the dashboard (Publishing) or via seovyn_api_request — which implies this tool is for viewing state, not connecting. However, it never explicitly says when to call this tool, so the positive trigger 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 covered; the description adds the default-action behavior and the fields list returns (status open/written/skipped and provenance). For a mixed read/write tool it still omits whether add is idempotent on a duplicate keyword, what happens to already-written articles when a target is removed, and any required permissions.

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

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

A single sentence that front-loads the resource definition, then the default action, then the mutation payloads. No filler, and the parenthetical list of returned fields is dense but each element earns its place.

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

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

For a 4-parameter, no-output-schema tool with mixed read/write actions, the description covers the default action, the per-action parameter requirements, and what list returns. Missing only the return behavior of add/remove and any org-resolution prerequisite, which are minor gaps given the schema documents org.

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

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

Schema coverage is only 25% (only org is documented), so the description must compensate, and it does: it maps parameters to actions ("add" { keyword, pageType? }, "remove" { keyword }) and marks pageType optional. This per-action conditionality is not expressible in the flat schema, so it adds real value; it still doesn't define keyword format or what pageType values mean beyond the enum.

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 resource ("The keywords Seovyn writes for (each becomes an article)") plus the three actions it exposes, so the agent knows it manages a keyword-target list rather than articles themselves. It does not name or contrast any sibling, but the enumerated action set makes it distinguishable from seovyn_list_articles and seovyn_write_article.

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?

Declares "list" as the default action and gives the shape of add/remove payloads, which implies when each is used. There is no explicit guidance on when to remove vs. mark skipped, no prerequisites (e.g. whether the org must be resolved first), and no when-not-to-use note relative to siblings.

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

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

The annotations declare destructiveHint=false, which in MCP semantics means the tool performs only additive updates, yet the description exposes a 'remove' { factId } action that deletes stored knowledge. That is a direct conflict with the declared safety profile; the description also says nothing about reversibility, permissions, or the side effects of 'refresh'.

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-loads the resource definition, then delivers an action-by-action payload table that is terse but information-dense; nearly every clause carries a parameter mapping or default. The telegraphic style is slightly compressed but wastes little space.

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 six-action, eight-parameter tool with no output schema and only minimal annotations, the description covers inputs thoroughly but says nothing about what 'list' returns or the shape of questions/answers, and never addresses the destructive 'remove' semantics. Adequate on the input side, incomplete on behavior and returns.

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 13% (just 'org' is documented), but the description compensates well: it defines the full action enum and maps payload parameters to actions (questionId/answer/topic/pageType for 'answer', text for 'add_note', factId for 'remove'), including the note that topic/pageType come 'as the question gave them'. Only the top-level types of the remaining params are left implicit.

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 (first-hand business knowledge: site-read facts and owner notes) and enumerates all six actions with their payloads, so an agent knows this is the knowledge-store tool with a set of read and write verbs. The opening clause is grammatically dangling ('which articles draw on'), which slightly muddies the framing, but the action inventory makes the purpose unambiguous.

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

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

It states the default action ('list' (default)) and sketches each action's intent ('questions': what Seovyn would like the owner to answer; 'refresh': read the site again now), which is implied usage guidance. But there is no explicit when-to-use/when-not, and no routing to adjacent siblings such as seovyn_sources or seovyn_edit_article, leaving the agent to infer selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: newest-first ordering, and that "pending" conflates drafts waiting, in-progress, and failed items — a non-obvious aggregation an agent would otherwise misread.

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 dense sentence that front-loads the resource and ordering, then the status meanings. Slightly run-on with nested parentheticals, but nearly 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?

No output schema exists, and the description compensates by stating what each returned article carries (keyword, quality score, publication location, search performance). A read-only tool with annotations and a near-complete param breakdown is adequately covered; pagination behavior is the only unaddressed element.

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 67%, with org and limit documented in-schema; the status enum values carry no schema descriptions. The description compensates by defining all four enum values semantically, which is the gap the schema leaves and more than the baseline 3.

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 (articles) and its defining behavior (newest-first ordering, status-filtered listing), which separates it from single-article siblings like seovyn_get_article. The verb 'list' is only implied, but the status taxonomy makes the retrieval semantics 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?

Explaining that "pending" is the review queue tells the agent which status to pick for that intent, so usage is implied for the main scenarios. However, it never states when to prefer this over seovyn_get_article, seovyn_publish_queue, or seovyn_results, and there are no exclusions.

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 say readOnly=false and destructive=false, so the description carries the real burden here and does so well: it discloses that checkout charges nothing until the user pays, and that change previews the current charge before applying with confirm. This is exactly the kind of irreversibility/confirmation behavior the annotations omit. It stops short of describing failure modes or what happens to an existing subscription mid-cycle.

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 dense sentence per action with the default called out first and no filler or restatement of the name. It is slightly run-on; the action list could be broken into bullets for faster scanning, 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?

With four parameters, no output schema, and a mutating action, the description covers the full lifecycle: read the plan and next charge, get a link, or preview-then-commit a change. The absence of an output schema is offset by describing what overview and change return. Minor gaps remain on error handling and proration behavior.

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 50% (org and confirm are documented; action and plan are bare), and the description compensates by explaining each action's meaning and the allowed plan values pro|scale. The confirm workflow (set true only after the preview was returned without it) is understood end-to-end. It does not add format detail beyond enum 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?

The description names the resource (the organization's plan and billing) and enumerates the three concrete operations the tool performs, each with a quoted action name. An agent can distinguish overview / checkout / change from each other and from unrelated siblings 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?

It clearly conditions each action: overview is the default, checkout is for obtaining a payment link, and change is explicitly for an organization that is already paying. The checkout-vs-change split is the key routing decision and it is spelled out. There is no explicit when-not guidance or reference to a sibling tool for adjacent billing questions.

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 useful context by clarifying that the queue contains approved items with a publishing pace and due dates, but says nothing about ordering, pagination, or volume.

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 fragment that conveys the resource, its state, and the key returned attribute with 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?

No output schema exists, so the description must carry the return-value burden, and it does so adequately by stating that entries include due timing. Pagination and ordering behavior are the only notable omissions for a simple read 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 coverage is 100% and the single 'org' parameter is fully described in the schema, including the default behavior when omitted. The description adds no parameter guidance, 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?

The description names a specific resource (approved articles awaiting publication) and adds the distinguishing detail of due timing, which separates it from siblings like seovyn_list_articles. However, the verb is only implied rather than stated, so it reads more like a definition of a concept than an action the tool performs.

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 explicit when-to-use instruction and no alternatives are named, even though seovyn_list_articles and seovyn_results are obvious adjacent tools. The content description hints at the use case but leaves routing entirely 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 by structured data. The description adds genuinely useful context the annotations lack: the data source is Google Search Console and the reporting window is 'since Seovyn started'. It does not describe return shape, pagination, or whether GSC must be connected, so it goes beyond annotations but only modestly.

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?

One sentence with no filler, and the headline metric set (clicks, impressions, positions) is front-loaded before the secondary items. Slightly list-heavy, but nothing is redundant.

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 reporting tool with no output schema, the description does enumerate the returned content categories (GSC metrics, best/rising articles, site trajectory), which is what an agent needs to decide relevance. It stops short of describing the response structure or time granularity, but the core is covered.

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% for the single 'org' parameter, and the schema itself explains the accountId/website/name forms and the omitted-default behavior. The description adds no parameter detail at all, so the baseline of 3 is appropriate.

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

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

The description names a concrete resource and content set: Google Search Console clicks, impressions and positions, plus best/rising articles and site-level performance. That is specific enough to distinguish it from siblings like seovyn_status or seovyn_competitor_pages, though it is phrased as a noun clause ('What the articles have earned') rather than an explicit verb, and it never names an alternative tool.

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, no prerequisites, and no mention of when another sibling (e.g. seovyn_status, seovyn_competitor_pages) would be the better choice. Usage is only inferable from the content list ('performance reporting'), which is weak guidance for a 23-tool namespace.

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: it discloses that approve publishes to the live site (now or at the publishing pace) and needs confirm, that retry consumes one of the month's article allowance and needs confirm, that hold prevents autopilot publication, and that reject reasons feed Seovyn's learning. Side effects, quota consumption, and the two-step confirmation flow are all surfaced.

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-loads the core action and keeps the whole definition to a single dense block that maps one clause per decision, so nothing is wasted. The semicolon-chained structure is slightly run-on and harder to scan than a list, but sizing is right for six decision branches.

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 every decision branch, the confirm/preview protocol, and the reason taxonomy, which is what an agent needs to call a six-parameter mutation tool with no output schema. Return-shape detail is minimal (only the implied preview), but the description references that preview explicitly, leaving little critical 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 coverage is only 50%, and the description compensates meaningfully: it supplies the allowed reason values (inaccurate, off-brand, thin, duplicate, off-topic, bad-seo, other), explains that note is optional but teaches Seovyn, and clarifies that confirm is only set after a preview. The decision enum values are expanded with prose semantics beyond the raw enum list, though org and itemId remain schema-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 and resource ('Decide on an article') and then enumerates every decision value with its concrete effect, so an agent can distinguish it from seovyn_edit_article, seovyn_write_article, and seovyn_publish_queue. The scope of the tool is unambiguous.

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

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

Gives clear when-to-use guidance for each decision branch (approve publishes, reject records a reason, hold suppresses autopilot, retry re-writes a failure, publish_refresh/discard_refresh apply to refreshed live articles) and flags which branches need confirm. It does not explicitly route to sibling tools such as seovyn_edit_article for text changes, so it stops short of full alternative coverage.

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 usefully adds that the result is returned WITHOUT saving, that a quota is consumed (one of the plan's monthly rewrites), and that confirm is required after a preview. That is real behavioral context beyond the structured fields, though reversibility of the quota spend is not discussed.

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?

Dense but front-loaded: the core action and per-parameter meaning come first, then the save/confirm workflow. Slightly run-on across sentences but 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 fills the gap by describing the return (the new section plus the whole body). It covers the confirm workflow and quota, making it sufficient for correct invocation, though quota exhaustion behavior is left unstated.

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 57%, and the description carries the undocumented index and heading parameters, explaining the 0 = opening convention and null-for-opening case, plus examples for instruction. It adds meaning beyond the schema, though org/body/confirm semantics remain only in the schema.

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

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

States a specific verb (rewrite) and a precisely scoped resource (one section of a draft) driven by an instruction, with concrete instruction examples. It is clearly distinguished from sibling seovyn_edit_article, which it names as the saving 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?

Explicitly routes the agent: this tool rewrites, and saving must be done via seovyn_edit_article, plus the confirm-only-after-preview rule. It also scopes the tool to the plan's monthly section rewrites, giving a clear usage context. No explicit when-not-to-use, keeping it below 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 declare readOnlyHint=false and destructiveHint=false; the description adds that 'remove' requires a confirm step and that 'discover' triggers an immediate scan. Those are meaningful behavioral facts beyond the annotations. It does not, however, describe the preview flow that the confirm param references.

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 dense sentence packs the default, all four actions, and their parameters with no filler. The telegraphic style is slightly compressed but front-loads the essential purpose before the action list.

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-parameter, multi-action tool with no output schema, the description covers the action space, defaults, and the destructive-path confirmation. It is close to sufficient, with only the return shape and the confirm-preview workflow left unstated.

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% (org and confirm), so the description must compensate. It does so by mapping each action to its expected inputs (type/label/url/pageType for add, sourceId for discover and remove), giving semantic shape to otherwise bare parameters. It leaves the relationship between url and type implicit.

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 clear role statement — 'Where Seovyn finds topics' — and enumerates the operations, so an agent knows this is the topic-source registry. It does not explicitly contrast itself with siblings like seovyn_topic_clusters, but the resource (sources) is distinct and 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?

It specifies the default action ('list'), what each non-default action does, and the precondition for removal ('needs confirm'). It stops short of stating when to reach for this tool versus a sibling, but the intra-tool routing is explicit and actionable.

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 a broad read-only aggregate spanning counts, billing/plan, month-scoped usage, and integrations. It does not disclose cost, response size, or whether the aggregation is expensive across many integrations, which with annotations in place is a modest 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?

A single dense sentence with no filler, front-loading the resource ('How an organization stands') before the field list. The parenthetical enumerations are long but each item earns its place by telling the agent what data comes back.

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 return content, and it does so explicitly across all three data groups. It could be complete at 5 by noting that the data is a point-in-time snapshot and whether it spans all integrations.

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 description already explains the org identifier, accepted forms (accountId/website/name), and the omitted-default behavior. The description adds nothing about the parameter, so baseline 3 is correct.

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 enumerates exactly what the tool aggregates — source/draft/published/approved/rejected counts, plan and monthly usage, and integration states — so an agent can tell it is an org-level status snapshot. It lacks an explicit verb and never names the overlapping siblings (seovyn_plan, seovyn_integrations), which keeps it from 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?

There is no guidance on when to call this versus seovyn_plan or seovyn_integrations, even though those siblings surface a subset of the same data. The only conditional hint is the optional-org fallback, which is usage context for a parameter, not for tool selection.

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

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

The description usefully discloses that 'remove' drops the cluster AND its unwritten keywords and requires confirm, which is exactly the kind of context annotations cannot express. But this squarely contradicts the annotation destructiveHint=false: a tool that deletes clusters and keywords is destructive, so the declared hint actively misleads an agent about the safety of the remove action.

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 dense sentence that front-loads the resource and then the actions, with zero filler. The parenthetical style is compact to the point of being terse, 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 4-parameter, no-output-schema, multi-action tool the description covers the actions and the destructive/confirm behavior, which is the critical part. It still leaves the return shape of 'list'/'plan', the exact effect of 'plan', and the 'org' parameter 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 only 50%, so the description must compensate. It adds genuine meaning for the 'action' enum values and for 'clusterId' (only relevant to remove) and flags that 'confirm' gates removal, but 'org' is left entirely to the schema and 'plan' is unexplained. It partially, not fully, offsets 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 names the resource precisely ('Topic clusters (a pillar keyword and its supporting ones)') and enumerates the three actions it exposes (list/plan/remove), so an agent knows exactly what the tool operates on. It doesn't distinguish itself from the overlapping sibling seovyn_plan, which keeps it from 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?

Each action carries a short parenthetical that implies when to use it (list is default, plan pulls more from the website, remove drops the cluster and needs confirm), which is real guidance. However, there is no explicit routing against alternatives such as seovyn_plan or seovyn_keyword_targets, so 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=true and destructiveHint=false, so the safety profile is covered. The description goes further by enumerating what the response contains (plan, supervised/autopilot mode, articles used this month) and the keys available for subsequent calls, though there is no output schema to corroborate it and no mention of failure behavior for an invalid or expired key.

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, front-loaded with the imperative 'Call this FIRST' so the routing instruction is read first. The organization parenthetical is dense but every listed field earns its place; only the run-on length of the second sentence costs a point.

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 field-by-field, and it supplies the cross-tool `org` convention. It stops short of covering error cases or confirming the response is static versus cached, but an agent has enough to call and use it 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?

The tool takes zero parameters, so the baseline is 4. The description does add meaning about the `org` parameter convention that sibling tools accept, which is not expressed anywhere in this tool's schema and helps the agent interpret and reuse the returned accountId/website/name 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 introspection verb and its exact returns: identity of the key, admin status, and the user's organizations with per-org fields. The 'Call this FIRST' framing and the organization context make it immediately distinguishable from sibling tools like seovyn_status or seovyn_create_org.

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 instructs 'Call this FIRST,' giving an unambiguous sequencing rule rather than an implied one. It also explains the downstream convention that organization-scoped tools accept `org` (accountId, website, or name) and default to the current organization, which tells the agent how to use this tool's output.

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; the description adds real context: it consumes one article from the month's allowance, lands in the review queue as a draft, takes a minute or two, and requires confirmation. That is meaningful disclosure beyond the structured fields, though it omits failure modes or quota-exhaustion 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?

Front-loads the action ("Write an article now on a topic") and wastes little space. The inline parameter parenthetical and the terse "Needs confirm" clause are slightly clunky and partially duplicate the schema's confirm description, but overall it is compact.

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 mutation tool with no output schema, the description covers the key operational facts: quota consumption, resulting draft state, timing, and confirmation flow. The org parameter is left to the schema (which points to seovyn_whoami), so nothing critical 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 only 40%. The description adds meaning for competitorUrls ("1-4 competitor pages it should beat") and hints at optionality of pageType, but org, pageType's enum values, and topic are unexplained in the description. It partially but not fully compensates for the documentation 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?

Specific verb (Write) and resource (article) plus scope (against 1-4 competitor pages it should beat). It is easily distinguished from seovyn_edit_article and seovyn_rewrite_section because it creates a new draft rather than modifying existing content, though it doesn't name those siblings 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?

Usage is implied by "Write an article now" and by naming the inputs, and it notes the confirm protocol, but there is no explicit when-to-use vs when-not or routing to alternatives like seovyn_plan or seovyn_edit_article. Adequate but leaves the agent to infer selection.

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