yetty

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

Annotations already confirm this is a read-only, idempotent, non-destructive, closed-world operation, but the description adds valuable context beyond them. It explains that the tool returns exact structure rules and why they matter: they decide whether the site converts into a clean editable CMS with named fields and add/remove collections, or a wall of generic 'Text' fields.

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

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

The description is front-loaded with the critical call to action and then efficiently explains what the tool returns and why it is important. Every sentence earns its place, with no filler or redundancy.

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

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

With no parameters, no output schema, and annotations already covering safety and idempotency, the description is complete enough for an agent to know exactly what the tool provides. It explicitly describes the return content as exact structure rules and details their impact on CMS conversion.

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

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

The tool has zero parameters, so there is no parameter semantics to explain, which matches the baseline score of 4. The description reinforces this by explicitly saying 'no arguments'.

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 returns yetty's exact structure rules for authoring HTML. It clearly distinguishes itself from sibling tools like yetty_login or yetty_batch_start by being a prerequisite guide with no account or arguments required.

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 opening imperative 'READ THIS BEFORE WRITING OR SENDING ANY HTML' gives explicit timing and context for use. It further removes friction by noting no account is needed, it is free and instant, and takes no arguments.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, yet the description still adds real behavior: 'Nothing is processed yet' and that owner approval happens by email. It omits whether re-closing is safe and what the call actually 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 tight sentences with the action front-loaded and the next step trailing. Efficient, though the unexplained 'parked'/'park_ref' terminology costs some clarity per token.

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 state-changing tool with no output schema, the description leaves the return value undefined — an agent cannot tell where the park_ref used by yetty_signup comes from. The lifecycle hint ('nothing is processed yet') is helpful, but the preconditions and output are underspecified.

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 single parameter batch_ref is never explained, so the description must carry that load but does not. Worse, it introduces a differently named 'park_ref' in the follow-up call without clarifying whether that is the value this tool yields or a separate field.

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 concrete verb and resource ('Close the parked batch'), which distinguishes it from siblings like yetty_batch_start and yetty_batch_file. However, 'parked batch' is unexplained jargon, so an agent must infer what state the batch is in when this applies.

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 forward: 'next call yetty_signup {email, park_ref}', which is exactly the sequencing guidance an agent needs. It does not, however, state when to prefer this over the sibling batch tools or what preconditions must hold.

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 safety profile is covered. The description adds genuinely useful context beyond that: the return shape {received_bytes, sha256} and the verification-and-resend workflow for hash mismatch, plus the 'send EXACT bytes, never retype' caution.

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 action, then telegraphic arg notes and the verification contract. Every clause carries information; nothing is padded or repeated from the schema.

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

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

With no output schema, the description correctly discloses the return values, and with 0% schema coverage it documents all four parameters. It omits the surrounding workflow (that a batch must first be started, and that the batch is finalized elsewhere) and any limits on file size or count, which are the remaining gaps for a 4-parameter batch 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 0%, so the description must carry all parameter meaning, and it does: batch_ref is identified as the pk_... park_ref, path is relative and folders are allowed, and content vs content_base64 is clarified as text OR binary. It stops short of saying whether the two content fields are mutually exclusive in practice or what happens if both are supplied.

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

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

States a specific verb and resource with scope: 'Add ONE file to the parked batch.' The count constraint ('ONE') and the reference to a 'parked batch' distinguish it from siblings like yetty_batch_start and yetty_batch_end, and an agent can tell immediately what it does.

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 'parked batch' implies a prerequisite (a batch created via yetty_batch_start and presumably closed with yetty_batch_end) and 'Add ONE file' implies one call per file, but neither the prerequisite nor the sequencing is stated explicitly. There is no named alternative or exclusion, 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?

Adds rich behavioral context beyond annotations: files are stored but NOT processed until owner approves by email, no account needed, and the returned park_ref should be reused as batch_ref. Annotations only say readOnlyHint=false and non-destructive; the description earns its keep by explaining the parked/approval semantics.

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

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

Front-loads the key insight (no account, parked batch) and then provides a concise workflow example. The example is dense but each element maps to a distinct sibling tool; no filler sentences. Slightly longer than strictly necessary but well structured.

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

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

For a zero-param orchestration starter tool with no output schema, the description covers purpose, behavioral quirks (parking, email approval), return value semantics, and the full downstream call sequence. Nothing an agent needs to invoke it correctly is missing.

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

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

Zero parameters, so baseline 4 applies. The description also clarifies the return value park_ref which is used downstream as batch_ref, adding useful semantic linkage even though there are no inputs to describe.

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

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

States a specific verb+resource: 'start a PARKED file batch' with the key twist 'send the site now, authenticate after.' Distinguishes itself clearly from siblings like yetty_batch_file and yetty_batch_end by naming it as the entry point of the batch flow.

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 positions this as the first step for users with no account, then walks the full sequence of subsequent tool calls. The full workflow example is essentially a when-to-use guide that routes an agent through yetty_batch_file, yetty_batch_end, yetty_signup, and yetty_claim_status.

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: the api_key is returned ONCE, the Bearer auth scheme needed for the full toolset, and the human verification step (owner opens email and types user_code). These are consequential traits the annotations (idempotent, non-destructive) do not convey.

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

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

A single front-loaded sentence whose state transitions are packed into an arrow chain. Every clause earns its place, with the primary action stated first and detail following.

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

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

Given the state-machine complexity and auth implications, the description covers transitions, required actions, and the api_key handoff well. No output schema exists and the returns are still explained, but the park_ref input is left 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 0% for the single required park_ref parameter, and the description never defines it, its format, or where it comes from. Only the vague 'parked upload' phrasing hints at its meaning, leaving the parameter undocumented.

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 ('Check a parked upload') that clearly separates it from siblings like yetty_status and yetty_login_status. The state-machine framing signals exactly what the tool reports on, though the term 'claim status' vs 'parked upload' is slightly loose.

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

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

Provides an explicit decision tree per state: when parked, send yetty_signup; when awaiting-approval, the owner acts; when approved, reconnect with the api_key. This names the alternative action for at least one branch, though it never states explicitly when not to call it.

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

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

Annotations only declare mutation/non-idempotency; the description goes well beyond by laying out the full async flow, the exact return shape ({login_ref, user_code}), the one-time nature of the api_key, and the ~20s polling cadence. This is exactly the behavior the annotations cannot convey.

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

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

Purpose is front-loaded and every line carries information (trigger, flow, poll interval, one-time key). The arrow-notation flow is dense and slightly awkward to parse, 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 no output schema and a minimal input schema, the description supplies both the trigger and the downstream flow, including where the api_key appears and the reconnect command. Nothing an agent needs to call and complete this login 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 0%, so the description must carry the parameter, and it does so with a concrete invocation example ({email:"owner@x.com"}) plus the semantic that the email belongs to the OWNER. It stops short of stating format constraints or validation behavior, so not a full 5.

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

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

States a specific verb+resource+scope ('Sign the OWNER in by email') and immediately scopes that it covers both existing and new accounts, which separates it from the yetty_signup sibling. An agent can identify this as the authentication entry point 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?

Explicit trigger condition: 'Use this whenever you are unauthenticated or your token expired.' It also routes forward to the alternative sibling (yetty_login_status) as the required polling step and distinguishes new-account handling from a separate signup path.

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 safety/identity hints (readOnlyHint=false, idempotentHint=true, non-destructive), so the description carries the real behavioral load. It discloses a genuinely important trait: the api_key is returned ONCE, plus the meaning of the pending state ('owner has not typed the code yet'). It omits expiry/polling-limit behavior for the pending state, so not a 5.

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

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

The state semantics are front-loaded in the first clause, which is the right order. The reconnect shell command is long and could arguably live in a doc, but it is concrete and immediately actionable rather than 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 single-parameter, no-output-schema tool, the description covers the return value (api_key once) and the action to take afterward, which is what an agent actually needs. The only gap is where login_ref originates and what to do if the status never leaves pending.

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

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

Schema description coverage is 0% and login_ref is undocumented in both schema and description; the reader must infer it comes from yetty_login. With one required parameter and no compensation in prose, the description falls short of the baseline it would otherwise enjoy.

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 ('Check an email sign-in') and describes the state progression (pending -> approved), which tells the agent what the tool observes. It does not explicitly differentiate itself from siblings like yetty_login or yetty_claim_status, which is the only thing keeping 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?

Usage is implied rather than stated: the pending->approved framing suggests polling after initiating a sign-in, and the reconnect example implies the tool is called to complete setup. There is no explicit 'call this after yetty_login' or 'do not use for X' guidance, and no named alternative among the nine 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 readOnly=true, idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds substantial non-annotation context: no authentication/account requirement, that delivery is free and instant, the non-removable hosted payment element, and the downstream workflow of returning the styled file. Return format and any rate limits remain unstated.

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 first sentence front-loads the purpose well, but the body is a single dense paragraph with nested parentheses (template names, data-yetty grammar references, and the Live-plan aside crammed into one trailing parenthetical). Every clause carries information, yet scannability suffers and the constraint rules are buried mid-paragraph rather than surfaced.

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 one-parameter, annotated, read-only fetch with no output schema, the description supplies everything an agent needs: what is returned, the available variants, the mandatory invariants after restyling, the no-JS rule, and the next action. Nothing material is missing given the richness of the annotations.

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 schema already lists the four keys, but the description goes beyond it by explaining the content and purpose of each template (checkout markup, buyer account page, order confirmation, payment frame) and the default. That semantic enrichment of the enum-like values adds real value over 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?

The description gives a specific verb ('Pull'), a well-defined resource ('a ready-made Yetty template file WITH its usage contract'), and enumerates the four concrete template variants with what each contains. It also distinguishes the base templates from the gallery-<surface>-<layout> layouts, so an agent can tell exactly what it is fetching.

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 operating conditions clearly (no account needed, free, instant), the redesign freedom ('restyle freely'), the hard exclusions ('NEVER remove or rename data-yetty-* marks', 'write NO cart/checkout/account JavaScript'), and the follow-up step ('send the styled file back'). It does not spell out when to prefer yetty_authoring_guide versus this tool, only cross-referencing it for grammar, so it stops short of explicit alternative routing.

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 mark it non-readOnly and non-destructive, and the description adds critical mechanics beyond that: the site is processed ONLY after the owner opens the email and types the code, the tool returns a short user_code, and the agent must show it and poll. This is exactly the kind of operational context annotations cannot convey.

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

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

Dense but front-loaded and waste-free: core action, trigger condition, args, then the immediate next step. Every sentence carries operational value.

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

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

For a two-param mutation with no output schema, the description covers the entire runbook: what it does, what it returns, the condition for processing, and the required polling. Nothing needed to call and follow up 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 description coverage is 0%, so both params are undocumented structurally. The description clarifies that email is the owner's email and park_ref is the parked upload reference, which compensates somewhat. However, it does not specify formats or constraints, so a 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 action and outcome: links a parked upload to an owner's email, sends approval email, returns a short user_code. Distinguishes itself from login/claim siblings by describing the email-approval flow. It does not explicitly name alternatives, but the workflow 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?

Implies when to use: after parking an upload, and directs the agent to show the owner the code and then poll yetty_claim_status every ~30s. This names a sibling and the timing condition. No explicit when-not-to-use guidance, but the workflow context is strong.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description adds real context by explaining that unauthenticated sessions can park a website via batch tools and start email sign-up, with the response clarifying how.

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, purpose front-loaded, then the precedence instruction, then the behavioral nuance. No filler or repetition.

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

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

For a zero-arg, read-only status probe with no output schema, the description covers what the tool is, when to call it, and what it enables when unauthenticated. It gestures at the response ('tells you exactly how') without describing return shape, which is a minor gap for a first-step 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to document and the description correctly does not invent any.

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 purpose — connection + authentication status — and the opening sentence names both resources clearly. 'Call this FIRST' differentiates it from the many sibling status/auth tools, though it doesn't explicitly contrast with yetty_login_status.

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 imperative 'Call this FIRST' gives unambiguous usage context, and the description notes what unauthenticated sessions can still do. It stops short of explicitly naming alternatives like yetty_login_status or yetty_login.

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