hello.new

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

Goes well beyond the annotations by disclosing that recipients need no account, that the link expires in 24 hours unless a hello.new account is connected, and that the caller must retain id and key to fetch files later — all operationally important context the annotations 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?

Three tightly packed sentences, front-loaded with the core capability and followed by usage, credential handling, and expiry — 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?

With an output schema present, return values need not be explained; the description covers the recipient's no-account flow, the credential handoff to list_files, and the expiry rule, leaving no critical gap for calling the tool 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 description coverage is 100%, so note, max_files, and expires_in are already fully documented with defaults and bounds. The description's expiry sentence adds only marginal reinforcement rather than new parameter meaning.

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 ('make a web page where a person can send you files') and clarifies the direction of transfer, which distinguishes it from sibling tools like share_page.

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 a clear triggering condition and concrete examples ('a signed document, a photo, an export'), and routes the agent to list_files for retrieval. It lacks an explicit when-not or negative case, but the context is 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?

Annotations only cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false). The description adds real behavioral value beyond them: request persistence ("Every request is stored") and the 24-hour expiry with its hello.new exception. It does not mention auth or rate-limit behavior, keeping it short of 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?

Three short sentences, zero filler. The core capability is front-loaded, followed by the reading path and the expiry caveat in priority order.

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 an output schema present, return values need no explanation, and the description covers the essentials an agent needs: what the tool produces, where the output surfaces (read_webhook_requests), and the lifetime constraint. Nothing material is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the expiry default and the note field. The description's expiry statement merely echoes the schema, adding no new syntax or constraint detail. Baseline 3 applies.

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

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

States a concrete verb+resource ("Make a URL") and clarifies the mechanism with examples ("Stripe, GitHub, a form, a cron job"). It is clearly distinguishable from create_upload_link by describing an inbound-callable endpoint, though it never names that sibling 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?

Gives strong usage context: the URL is meant to be called by external services, and requests are consumed via read_webhook_requests, which routes the agent to the right companion tool. It stops short of stating when NOT to use this versus create_upload_link.

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 destructiveHint=true, readOnlyHint=false, so the safety profile is covered. The description earns credit by adding concrete consequences beyond the annotations: deletion is immediate ('right away') and public-facing ('anyone who opens it afterwards gets a 404'). It still omits reversibility/auth requirements, but the consequence disclosure is genuinely useful.

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

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

Two short sentences, zero waste, with the destructive scope front-loaded before the post-condition. Ideal sizing for a simple two-parameter tool.

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?

An output schema exists, so return values need not be explained, and the description covers scope and the external consequence of deletion. The remaining gap is whether the action is recoverable or requires confirmation, which matters for an irreversible 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 description coverage is 100% and both required parameters (id, key) are documented in the schema as coming 'from the tool that made the link.' The description adds nothing about parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (Delete) and resource (link) with scope: 'everything in it' is removed. It doesn't explicitly contrast with siblings, but the sibling set (create_upload_link, get_link_stats, etc.) is functionally distant enough that disambiguation isn't needed.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer that this is the terminal removal action; nothing tells it when deletion is appropriate versus other link-management 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that a live dashboard URL (stats_url) is returned, which is useful behavioral context, but says nothing about data freshness, latency, or what happens for a link with zero traffic.

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 primary outcome and followed by the notable secondary return value. No filler and every clause carries information.

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 an output schema present and annotations covering the safety profile, the description needn't enumerate return fields, yet it does enough to tell the agent that both metrics and a shareable dashboard URL come back. Only minor gaps remain, such as noting the link must already exist and be owned by the caller.

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 both parameters are required, so the schema fully documents id and key (including their provenance). The description adds no syntax, format, or coupling details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('see who opened one of your links') and enumerates exactly what is measured: views, visitors, countries, devices, referrers and agent reads. This is unambiguous and cannot be confused with siblings like delete_link or create_webhook.

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 context is implied by the purpose (call it when you want engagement data for an existing link), but there is no explicit when-to-use guidance, no prerequisites, and no named alternative. Adequate but with a clear gap.

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/no-destructive safety, so the bar is lower; the description adds genuinely useful behavior by disclosing that small text files return inline while others carry a download_url, and that wait up to 20s long-polls for the first file. That is real operation-level context beyond 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?

Three tight sentences with the action front-loaded, followed by return-shape behavior and the optional wait semantics. Every sentence earns its place 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?

An output schema exists, so return structure need not be spelled out, yet the description still usefully previews inline vs download_url handling. Combined with complete parameter coverage and clear safety annotations, 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?

Schema description coverage is 100%, so all three parameters are documented in the schema itself; the baseline is 3. The description restates the wait semantics ('wait for the first file to arrive') but adds no syntax or defaults beyond what the schema already says.

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 ('List the files people sent to one of your upload links'), which is unambiguous and separable from siblings like get_link_stats or create_upload_link. It does not explicitly name a sibling to contrast against, so it falls just short of 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: it operates on an existing upload link whose id/key come from 'the tool that made the link', and the wait parameter implies a polling/waiting scenario. But there is no explicit when-to-use or when-not-to-use guidance against alternatives such as get_link_stats.

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 (openWorld, not read-only, not destructive), it discloses genuinely new traits: everything published is public, no server code runs, the link expires in 24 hours unless a hello.new account is connected, and the returned id/key are needed for future updates. These are exactly the consequences 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?

Three tight sentences, front-loaded with what the tool does, then the credential handoff, then the constraints. Every clause carries information; nothing is padding.

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 an output schema present, return values need not be explained, and the description covers everything else an agent needs: static-only constraint, public exposure, expiry behavior, and the alternative tool for edits.

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

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

Schema description coverage is 100%, so files/title/expires_in are already fully documented in the schema, including the index.html convention and 100-file/10MB limits. The description mirrors the expiry default rather than adding new parameter meaning, so the 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?

The description names a specific verb (publish) and resource (a website built from HTML/CSS/JS/images) served at its own public URL. It distinguishes itself from the sibling update_site by explaining that id and key are kept specifically to change the site later.

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 clear context for use (a static site the user built that others should visit) and routes modification to update_site. It does not state when *not* to use it, e.g. when a dynamic/server-backed app is needed, though the 'static files only' line partly covers this.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it reveals the returned request parts, incremental polling via 'after', and a blocking wait of up to 20 seconds.

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

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

Two tightly written sentences with zero waste. The first sentence front-loads purpose and return contents; the second efficiently explains the two optional parameters. The minor 'wait ... to wait' repetition does not undermine the conciseness.

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 4 parameters, 2 required, full schema coverage, and an output schema, the description supplies all needed invocation context. Safety is covered by annotations, return shape by the output schema, and polling behavior by the description.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including 'after' and 'wait'. The description reinforces these semantics (newer requests, up to 20 seconds) but adds no format details, edge cases, or defaults beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb 'read' and resource 'requests your webhook URL received', and enumerates the returned fields (method, headers, query, body). It does not explicitly differentiate itself from sibling tools like get_link_stats or list_files, so it falls short of a 5.

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

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

The description implies usage by explaining incremental retrieval with 'after' and long-polling with 'wait', but it never explicitly states when to use this tool versus any alternative. Sibling tools are unrelated operations, so no clear alternative selection guidance is provided or needed.

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, openWorldHint=true, destructiveHint=false), and the description goes beyond them by disclosing the key behavioral trait: the link expires in 24 hours unless a hello.new account is connected, plus that the page is publicly readable by anyone with the URL. It does not address permissions, rate limits, or whether content is retained after expiry.

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 and kept to two compact sentences with no filler. It could be tightened slightly by folding the expiry clause more directly into the main statement.

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 an output schema present, return values need no explanation, and the description covers the essential behavior (public visibility, 24-hour expiry). The main gap is the absence of routing guidance versus create_upload_link.

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%, so the schema already documents title, content, and expires_in. The description only reinforces the expiry default, adding marginal value beyond the schema's own description of the same 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 verb and resource: publishing Markdown as a shareable web page, with concrete examples (report, summary, draft). It distinguishes itself well from most siblings, though it does not explicitly contrast with create_upload_link, the nearest neighbor for producing a shareable link.

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 examples and 'anyone with the link can read' imply the usage context, but there is no explicit when-to-use routing against create_upload_link or any statement of exclusions. Usage is inferable but not 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 flag destructiveHint=true and openWorldHint=true, but the description goes further by specifying exactly what is destroyed (files omitted from the payload are removed) and what is preserved (the URL). That is precisely the context an annotation cannot convey, and there is no contradiction.

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, zero filler, with the replacement semantics front-loaded before the file-completeness rule. 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?

For a three-parameter mutation tool with full schema descriptions, full annotations, and an output schema, the description supplies the one non-obvious behavioral fact (full replacement) plus the sibling relationship, leaving nothing an agent needs to call 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% and the nested file schema already documents path, content, encoding, the 100-file/10 MB limits, and that index.html is the home page. The description's emphasis on the complete file set reinforces schema semantics but adds no new per-parameter detail, so baseline 3 applies.

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

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

Names a specific verb ('Replace the files') and resource (a site published with publish_site), and states the effect on identity ('it keeps its url'). An agent can distinguish it from publish_site and create_upload_link 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?

Explicitly ties this tool to sites created via publish_site and gives the critical operating rule that every file must be sent because omissions are removed. It does not state when to prefer siblings like create_upload_link or what preconditions exist, so it stops short of full when/when-not coverage.

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