yetty

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

No annotations are provided, so the description carries the full transparency burden. It clearly states no account is needed, it is free/instant, has no arguments, and returns structural rules; this makes the tool feel safe and informational. It stops short of explicitly saying 'read-only' or describing network behavior, but the framing is sufficient for a zero-argument guide tool.

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

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

The description is one dense sentence but front-loads the directive 'READ THIS BEFORE WRITING OR SENDING ANY HTML' and packs relevant details efficiently. The long parenthetical and em-dash list add value without fluff, though it is slightly overstuffed.

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-argument documentation tool with no output schema, the description fully explains what the tool returns, when it should be consulted, and why it matters. It even summarizes the likely decision outcome, making the tool self-sufficient.

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

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

The tool has zero parameters and the description reinforces that clearly with 'no arguments'. Since there are no parameter semantics to explain, the description fully covers the input side.

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

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

The description clearly states the tool returns yetty's exact HTML authoring rules and even lists the categories of rules covered. It is specific and distinguishes itself from sibling tools that handle login, batch operations, and status checks.

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

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

The description explicitly instructs the agent to read this tool before writing or sending any HTML, providing a clear entry-point cue. It does not spell out when-not-to-use or name alternative tools, but the sibling list makes the context unambiguous.

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 no annotations provided, the description carries the full burden. It usefully discloses that closing does not process anything and that the batch is later approved by email. However, it does not explain whether the close is reversible, idempotent, or whether any state/permission requirements exist.

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

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

The description is two brief sentences that pack in the action, a key behavioral caveat, and the next-step call. No filler or redundant phrasing.

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 transition tool, it covers core purpose and workflow context well. The main gap is the lack of guidance on how to obtain/format batch_ref and no mention of response behavior, but this is not severe for a simple close operation.

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 description never mentions batch_ref, leaving the only required parameter unexplained. The name suggests it is a batch reference, but the description does not define its format, source, or relationship to the parked batch.

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 the imperative 'Close the parked batch', naming both the action (close) and the resource (parked batch). This clearly distinguishes it from siblings like yetty_batch_start and yetty_batch_file.

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 explicit workflow context: 'Nothing is processed yet — next call yetty_signup {email, park_ref}' tells the agent the appropriate next step after this tool. It doesn't state when not to use it or name alternatives, but the context is clear enough.

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

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

No annotations are present, so the description carries the full burden. It discloses the return payload {received_bytes, sha256}, instructs verification against the local copy, and warns to send exact bytes and resend on mismatch. This is strong behavioral guidance, though it omits error cases and edge behaviors.

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

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

The description is two sentences with front-loaded purpose, followed by parameters and return/verification behavior. Every sentence earns its place and there is no filler.

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

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

For a tool with no output schema and no annotations, the description covers purpose, parameters, return hash, and verification workflow. It leaves minor ambiguity about whether exactly one content field is required and batch lifecycle boundaries, but is otherwise 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 0%, and the description compensates fully. It explains batch_ref as the pk_... park_ref, path as relative with folders allowed, and content/content_base64 as text vs binary alternatives, adding meaning far beyond the raw schema field names.

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 'Add ONE file to the parked batch,' a specific verb+object+context statement. It clearly distinguishes this from siblings like batch_start and batch_end by emphasizing single-file addition to an existing parked batch.

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

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

The description gives clear context: use this to add one file to a batch referenced by batch_ref, and the phrase 'parked batch' implies it fits between batch_start and batch_end. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Given no annotations, the description carries the full burden of behavioral disclosure. It clearly states that no account is needed, that files are stored safely but not processed until owner approval via email, and that the return value park_ref should be used as batch_ref. This gives the agent a clear expectation of side effects and prerequisites.

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

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

The description is a bit long due to the example, but it is well-structured: first sentence states purpose, then explains behavior, then provides a step-by-step example. The example is valuable and earns its place. Slightly overlong but acceptable.

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 tool with no parameters and no output schema, the description is complete. It explains the workflow, the return value, the authentication flow, and how it connects to sibling tools. The example covers the entire sequence, making it self-contained for an agent.

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 0 parameters, so the description adds nothing beyond the schema. Baseline for 0 params is 4, and the description still clarifies the output park_ref, which is relevant. No parameter details 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 clearly states the tool's purpose: 'start a PARKED file batch' with a specific verb and resource. It distinguishes from siblings by emphasizing that it is the initial step for unauthenticated batch operations, and the example workflow shows how it fits with yetty_batch_file and yetty_batch_end.

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

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

The description provides explicit usage context: no account needed, and it shows the exact sequence (start → file → end → signup → claim). It implicitly says when to use this tool (to begin a batch without authentication) and the example clarifies how it differs from later steps. This is strong guidance for selecting the right tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly warns that the api_key is returned ONCE and instructs how to reconnect, plus it outlines the full state progression. This is substantial, non-obvious behavior that an agent must know to avoid losing the 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?

The description is a single dense sentence that packs a state machine, action guidance, and authentication instructions. It is front-loaded with the core purpose, and every clause adds information. The length is a bit high, but it is efficient and clearly structured as a state transition chain.

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

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

The description explains the lifecycle, the once-only api_key, the waiting_url, and the reconnect method, which are essential for correct use. However, it does not describe the response shape for parked or awaiting-approval states, nor does it mention error handling for invalid park_ref. Given no output schema, those details would improve completeness.

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 input schema only shows 'park_ref' as a required string with no description, and schema description coverage is 0%. The tool description implies park_ref is the identifier of the parked upload, but it never explicitly defines where the value comes from or its format. The self-descriptive parameter name helps, but the description does not fully compensate for the missing schema documentation.

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 'Check a parked upload,' a specific verb and resource that clearly states the tool's function. It goes further by enumerating the possible states, which distinguishes this claim-status check from generic status tools like yetty_status. The mention of yetty_signup also links it to the upload 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?

The description gives conditional guidance for each state: send yetty_signup when parked, have the owner approve when awaiting-approval, and reconnect with a bearer token when approved. It implies this tool is used to poll a previously parked upload, though it does not explicitly exclude alternatives or state when not to use it.

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

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

No annotations exist, so the description carries the full burden. It discloses the interactive flow (show user_code, user opens emailed link, types code, poll status), the ~20s polling interval, the one-time return of api_key, and the exact reconnect command. It doesn't mention side effects like whether the login expires or invalidates previous keys, but it explains the core behavior thoroughly.

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 dense but well-structured: it states the purpose, the flow, the call example, and the usage condition in a concise, scannable format. Every sentence adds information needed to execute the tool correctly.

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 tool's interactive login flow and no output schema or annotations, the description covers all essential aspects: when to invoke, what the call returns, what to do with the user_code, how to poll, and what final result to expect. It also references the sibling yetty_login_status and yetty_signup appropriately, making the context 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?

The input schema has only one parameter 'email' with zero description coverage. The description compensates by giving an example call with owner@x.com and clarifying this is for the OWNER's email. It doesn't explicitly say the email must be the owner's registered email or what format to use, but the example and context provide enough practical guidance.

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

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

The description clearly identifies the tool as an email-based login flow for the OWNER, distinguishes it from signup and status tools, and explicitly names the flow and its outcome. It even describes the exact call shape and what to do with the result, leaving no ambiguity about what yetty_login 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 description explicitly states when to use this tool: whenever unauthenticated or token expired. It also mentions alternatives by naming yetty_signup for new accounts when signups are open, and implicitly contrasts with yetty_login_status for polling. This provides clear routing guidance with 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?

With no annotations, the description carries the behavioral disclosure burden. It significantly helps by warning that the api_key is returned only ONCE and by including reconnect instructions. It does not mention error cases or whether repeated checks have side effects, but the one-time key disclosure is valuable and non-obvious.

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

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

The core behavior is front-loaded and the reconnect example is useful for acting on the approved state. The description is slightly long but every part serves a purpose, so it remains appropriately concise.

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

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

The description covers the main states and the approved response well, including the one-time key and reconnect steps. However, it lacks an explanation of where login_ref comes from and what the pending/approved response structure looks like, which an agent needs for fully reliable invocation.

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 needed to explain login_ref, but it does not state where login_ref comes from, its format, or how to obtain it. The term is somewhat inferable from the email sign-in context, but the description adds no explicit parameter semantics.

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

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

The description clearly states the tool's function: checking an email sign-in status, and it explains the pending -> approved transition. It is specific about the resource and action, though it does not explicitly differentiate itself from siblings like yetty_login or yetty_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 pending/approved state descriptions imply this is used after initiating an email sign-in and while waiting for the owner to enter a code. However, it gives no explicit guidance on when to poll, when not to use it, or how it compares to sibling status 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?

With no annotations provided, the description carries the full burden. It discloses that no account is needed, the operation is free and instant, and the pay-skeleton's payment element is hosted and non-removable. It also warns against removing data-yetty-* marks and writing custom JS, which informs the agent of critical constraints. It does not explicitly state the operation is read-only, but the pull semantics and 'no account needed' clarify it's a safe retrieval.

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 long but well organized: it opens with the core purpose, then lists the four templates with per-template details, then covers usage constraints, and finally the conditional live-plan extension. Each sentence adds distinct information, and the structure is logical. It could be tightened slightly, but it remains efficient for the amount of context it conveys.

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 tool with a single optional parameter, no output schema, and no annotations, the description is remarkably complete. It covers all template choices, explains the conditional regions and the grammar reference, provides explicit do's and don'ts (e.g., 'NEVER remove or rename data-yetty-* marks'), and mentions the live-plan option. An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100% with a simple enum of strings, so the baseline is 3. The description adds substantial meaning beyond the schema by explaining what each skeleton contains (e.g., 'checkout-skeleton' includes 'cart / checkout / thank-you markup with every data-yetty-component and data-yetty-slot mark'). This extra detail helps the agent choose the correct parameter value.

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 ('Pull') and a clear resource ('a ready-made Yetty template file WITH its usage contract'), and enumerates the four distinct template keys. It distinguishes the tool from siblings like yetty_authoring_guide (which is for grammar) and the batch/auth tools, so an agent can immediately see this is the template-pulling utility.

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 clear context for when to use the tool, including the template categories and the live-plan extra. It implicitly routes grammar questions to yetty_authoring_guide by mentioning the 'full grammar' is there, and it explicitly states constraints like 'write NO cart/checkout/account JavaScript of your own.' There is no explicit 'do not use this when...' statement, but the alternatives are implied through the sibling references.

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 no annotations, the description carries the full burden and does well: it discloses the email-sending side effect, the asynchronous gating ('processed ONLY after the owner opens the email and types that code'), the returned user_code, and the polling cadence. It does not cover failure modes, code expiration, or whether re-signup is possible, but the core behavioral contract is clearly exposed.

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 compact, front-loads purpose, then gives arguments, then highlights the critical instruction to show the code and poll. Every sentence adds necessary information, and the uppercase directive draws attention to the most important user-facing behavior without bloat.

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 tool's moderate complexity and absence of output schema and annotations, the description covers the main contract: inputs, output concept (user_code), asynchronous processing, and next step. It is missing error/expiration behavior and precise park_ref provenance, but it is surprisingly complete for a two-parameter flow 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 compensate. It clarifies that email is the owner's and that park_ref relates to a parked upload, but it does not explain where park_ref comes from, its format, or how to obtain it. The word 'park_ref' remains largely jargon-dependent, leaving a real gap for an agent trying to construct valid 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: link a parked upload to the owner's email, send an approval email, and return a user_code. It also names the follow-up sibling (yetty_claim_status), which distinguishes it from related tools in the flow. The 'ONLY after' clause clarifies the intended single-step role of this 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?

The description gives clear workflow context: use this to initiate owner approval for a parked upload, then show the code and poll yetty_claim_status every ~30s. It does not explicitly enumerate when-not-to-use alternatives, but the named follow-up action provides strong routing guidance. This is clear context without full exclusionary criteria.

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 no annotations, the description carries the full behavioral burden. It successfully discloses that unauthenticated sessions still permit website parking and email sign-up, and that the response tells the caller exactly how to proceed. This provides meaningful behavioral context beyond a bare status-check description.

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

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

The description is two sentences: the first instantly identifies the tool's role, and the second adds valuable operational context. Every word earns its place, and no redundant or filler content is present.

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

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

Given the zero-parameter schema and no output schema, the description covers the essential context: what this tool reports, when to call it, and a behavioral note about unauthenticated sessions. It could slightly expand on what the response looks like, but the pointer to 'the response tells you exactly how' is a pragmatic and sufficient signal.

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 and the schema is empty, so there is no parameter semantic burden for the description to carry. The baseline for zero-parameter tools is solid because the description has nothing to add and omitting parameter details 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 clearly states this is a connection and authentication status check, and further establishes its role by directing the user to 'Call this FIRST.' This differentiates it from sibling login/status tools by framing it as the entry-point status for the entire system.

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 explicit 'Call this FIRST' gives clear when-to-use guidance. It also provides contextual information about what is possible in unauthenticated sessions, giving the agent useful caveats, though it does not directly name alternative tools or specify when not to use it.

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