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?

No annotations are provided, so the description carries the full burden. It discloses key behaviors such as the api_key being returned 'ONCE' and the need to reconnect with a Bearer token for the full toolset. It also explains the state flow, which is transparent about what the tool reports.

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 lot of information efficiently. It is front-loaded with the purpose and then explains states and actions, 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?

For a status-check tool with one parameter and no output schema, the description covers the essential aspects: states, transitions, and return behavior (api_key once, waiting_url). It does not address error cases, but that is acceptable for such a simple 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% and the description does not explicitly define the park_ref parameter. However, the tool's name and the phrase 'Check a parked upload' strongly imply park_ref is the identifier for the upload. The description adds minimal value beyond what the name suggests, but it is not misleading.

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: 'Check a parked upload.' It uses a specific verb and resource, and the state-transition details distinguish it from siblings like yetty_status by focusing on the parked-upload lifecycle.

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 implicitly explains when to use the tool (after parking an upload) and provides explicit next steps per state, including referencing yetty_signup for the parked state. It does not explicitly state when not to use it, but the context is clear.

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 full responsibility for behavioral disclosure. It explains the flow in detail: returns a login_ref, requires the owner to click an emailed link, and then polling via yetty_login_status yields an api_key once and the reconnect command. It also notes the condition about signups being open. This is thorough and gives the agent a clear mental model.

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 well-structured: it starts with a concise summary, then presents a clear FLOW sequence with arrow notation, and ends with a usage directive. Every sentence contributes to understanding the tool's purpose and usage, with 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?

Without an output schema, the description compensates by explaining the return values (login_ref, then api_key and reconnect command). It covers the full lifecycle of login, including polling steps. The given context (single parameter, no complications) is fully addressed, making the description complete for an agent to act upon.

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

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

The schema only lists 'email' with a type of string, and the description adds meaning by specifying it's the OWNER's email and providing an example ('owner@x.com'). This clarifies the parameter's role but doesn't cover edge cases like format requirements or whether the email must be pre-registered. Given only one parameter, this is sufficient.

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 action ('Sign the OWNER in by email') and the resource (owner account). It distinguishes itself from siblings like yetty_login_status (which polls status) and yetty_signup (which handles signups) by detailing its own flow and when to use it. The phrase 'no dashboard, no key copying' further clarifies its role.

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 states when to use the tool: 'Use this whenever you are unauthenticated or your token expired.' It also provides a step-by-step flow, including when to poll yetty_login_status, giving clear guidance on the sequence. While it doesn't name alternative tools, it explains its own role fully and covers both new and existing accounts.

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 fully discloses key behaviors: the API key is returned only once, the status transitions from pending to approved, and it includes reconnect instructions. This goes beyond what a schema would show and the example is actionable.

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 mostly concise, opening with a clear purpose. The long reconnect example adds length but is directly useful and avoids fluff. The overall structure is logical, though the example could be trimmed without losing essential info.

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 return value (api_key ONCE) and the state flow, which is helpful given no output schema. However, it lacks explanation of the `login_ref` parameter and does not address error cases or what happens on repeated calls after the API key is consumed. This leaves some gaps for a simple 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 schema describes a single `login_ref` parameter, but the description provides no explanation of what `login_ref` represents. With 0% schema description coverage, the description must compensate, but it does not even mention the parameter, leaving its meaning ambiguous.

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: checking the status of an email sign-in. It distinguishes from siblings like 'yetty_login' and 'yetty_status' by focusing on the sign-in state (pending/approved) and the specific return of an API key. The verb 'check' and resource 'email sign-in' are explicit.

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

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

The description implies usage after a login attempt, explaining the pending-to-approved flow and providing a concrete reconnect example for Claude Code. However, it does not explicitly list when to use this vs. alternative status or login tools, nor does it state when not to use it (e.g., if login is not initiated).

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. It discloses a key behavioral trait: processing occurs only after the owner clicks the approval link. It also reveals the asynchronous nature by recommending polling. However, it omits failure modes, error handling, or any side effects beyond sending the email.

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 efficient, using two sentences to cover purpose, parameters, and follow-up actions. It is front-loaded with the main action and avoids unnecessary detail.

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?

Despite lacking an output schema and annotations, the description provides a complete operational flow: link upload, send email, poll status, and instruct the owner. It gives enough context to invoke and monitor the process, though it does not detail return values or error scenarios.

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

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

The schema provides no descriptions (coverage 0%), so the description must compensate. It clarifies that 'email' is the owner's email, adding semantic value over the bare schema. However, 'park_ref' remains undefined, leaving ambiguity for that parameter.

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

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

The description clearly states the tool's purpose: linking a parked upload to the owner's email and sending an approval email. This is a specific verb+resource pairing that distinguishes it from sibling tools like yetty_claim_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 description gives explicit post-call guidance: 'Then poll yetty_claim_status every ~30s. Ask the owner to check their inbox.' This clarifies the expected workflow. However, it does not explicitly state when not to use this tool or compare it with alternatives.

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.