Put It Online

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

Annotations only cover the coarse safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true). The description adds the operationally critical traits: the URL is one-time, the bytes go via PUT at that URL, and completion must be confirmed by polling for status 'live'. This is exactly the extra context the annotations cannot supply.

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 scoping condition, then the create→PUT→poll flow in order. No filler sentences; the parenthetical curl hint is genuinely actionable.

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-value explanation is unnecessary, and the description covers the full lifecycle an agent must drive: reserve, upload, poll. Nothing needed to invoke and follow through 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 slug, filename, password and size_bytes are already documented inline. The description only references slug and manage_token (the latter not even an input parameter) in the polling step, adding workflow context but no new parameter meaning. 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 (reserves a link, returns a one-time upload_url) and scopes it precisely to 'files too large to send inline', which implicitly separates it from the inline sibling upload_file. An agent can identify the job 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?

Gives clear context for when to use it ('too large to send inline') and an explicit post-call workflow: PUT bytes, then poll get_link with slug/manage_token until status is 'live'. It stops short of naming upload_file as the small-file alternative, so the exclusion is implied rather than stated.

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 and idempotentHint=true, but the description adds material context beyond them: the cascade to associated files, the irreversibility ('cannot be undone'), and the permission/manage_token model. It does not mention rate limits or error behavior, which keeps it from 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, front-loaded with the destructive action and its scope, then authorization, then irreversibility. No filler and nothing repeated from the title.

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 annotations cover the safety profile. The description supplies the remaining essentials an agent needs: scope (link plus files), authorization path, and irreversibility.

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 slug and manage_token are already documented with format examples in the schema. The description reinforces why manage_token exists (anonymous callers) but adds no syntax or format detail beyond the schema, which is the baseline-3 case.

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), resource (link), scope of effect (and its files), and permanence. No sibling tool performs deletion, so an agent can distinguish it from get_link/list_links/make_permanent without ambiguity.

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 the authorization context that governs use: account owners can delete their links, anonymous callers must supply the manage_token. There is no competing delete tool to route against, so no alternative is named, but the conditions for legitimate use are explicit.

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 this is a non-read-only, non-destructive, non-idempotent mutation, so the bar is lower; the description adds real value by explaining what happens (expiry clock restarts, expired links return) and what is untouched (permanent links), plus a plan-level prerequisite. It omits rate-limit or repeated-call behavior, but covers the mutation's effect well.

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, front-loaded with the action, then the effect, then the eligibility constraint. Each sentence carries distinct information with no repetition or 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 values need not be described. The description covers the action, its effect on expired vs permanent links, and the account/plan prerequisite — everything needed to invoke an annotated mutation 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?

Only one parameter, and schema coverage is 100% with an example format ('k3x9pq' or a full URL). The description adds no syntax or format detail 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 ('extend', "link's expiry clock") and clarifies scope: it applies to expiring/recently expired links only. The note that 'Permanent links are unaffected' implicitly separates it from the sibling make_permanent, so an agent can route correctly without opening schemas.

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 precondition ('Requires a connected account whose plan includes extending') and an exclusion ('Permanent links are unaffected'), which tells the agent when this tool is not the right choice. It does not explicitly name make_permanent as the alternative for permanent links, so it stops just short of full routing guidance.

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, idempotentHint=true and openWorldHint=false, covering the safety profile. The description adds no behavioral context beyond that — no auth/permission requirements, no freshness or caching behavior, no note on latency. What it does add (the returned fields) duplicates the existing output schema, so it earns little credit.

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 noun phrase with no filler. It is a sentence fragment rather than a complete sentence, which slightly weakens it, but every word 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, the description need not explain return values, and with no parameters and read-only annotations there is little else an agent requires. The only remaining gap is the absence of any usage context, which is minor for a parameterless account-info call.

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 there is nothing for the description to disambiguate; the baseline for a parameterless tool applies.

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

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

The description names the resource precisely ("the connected account's plan") and enumerates the returned data points (slots used/available, size limit, features), so an agent can tell it apart from link-management siblings. The verb is implicit rather than stated, but the title plus read-only annotations make the retrieval operation unambiguous.

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

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

Usage is implied by the content — an agent would call this when it needs account-level limits or feature availability. There is no explicit when-to-use statement, no mention of prerequisites, and no pointer to any sibling tool, so it stops short of real guidance.

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, idempotent and closed-world behavior, so the safety profile is covered. The description adds real context: views are null when the account plan has no view counts, removed links carry removed_reason and appeal_url, and anonymous callers need the manage_token. It stops short of describing pagination or output shape, which is acceptable here.

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

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

A single dense sentence that front-loads the status enumeration and appends the secondary facts about moderation, views and tokens. No filler, though the packed clause list makes it slightly hard to scan.

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, the description need not define return values, yet it usefully previews the status set and the null-views edge case. Combined with the auth note for anonymous callers, an agent has everything required to call this 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%, so both parameters are already documented, giving a baseline of 3. The description adds only the context that manage_token comes from creation and is used by anonymous callers, echoing 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?

The description names a specific verb+resource (link status) and enumerates the concrete status values returned, so the agent knows exactly what it retrieves. It does not explicitly contrast itself with siblings such as list_links or delete_link, 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: an agent can infer this is for checking one link's state, and it notes that anonymous callers must supply the manage_token they got at creation. There is no explicit when-to-use/when-not or routing to an alternative 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered; the description adds genuinely new behavior (newest-first, permanent-first ordering) plus an auth precondition. It still says nothing about result size limits or pagination behavior, which is a modest gap rather than a serious one.

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

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

One compact sentence in two clauses: what it returns with its ordering, then the precondition. Nothing is padding and the key scoping facts are front-loaded.

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

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

An output schema exists so return values need no explanation, and the ordering/precondition are stated. However, for a paginated list tool whose two paging parameters have zero schema documentation, the description leaves the practical mechanics of retrieval unexplained.

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 both parameters, so limit and offset are completely undocumented in the schema, and the description does not mention paging, defaults, or the 200 cap at all. The ordering sentence does not map onto either parameter, leaving an agent to guess how to page through results.

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+resource ('List the links') scoped to the connected Put It Online account, which cleanly separates it from get_link (singular) and delete_link. It does not explicitly name any sibling, so it falls short of a 5 despite the plural framing doing useful disambiguation work.

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 precondition 'Requires a connected account' and the ordering contract, which implies when the tool is usable, but it never says when to prefer this over alternatives (e.g. get_link for a single link) or whether the list is paginated/filterable. Usage is implied rather than guided.

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 the mutation/idempotency/destructive profile, and the description adds two things they don't: the operation consumes one of the plan's finite permanent slots (a quota side effect) and it requires an eligible connected account. It still doesn't say what happens when slots are exhausted or whether the action is reversible.

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 dense sentences that front-load the action and then the resource prerequisite; the cross-reference to get_account is inline 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 one well-documented parameter, a rich annotation set, an output schema, and an explicit account/plan precondition, the description is nearly self-sufficient. Only the edge case of slot exhaustion 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 100% for the single slug parameter, so the schema already documents format and accepted URL/name forms. The description adds no additional meaning about the parameter, which is the baseline case.

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 with scope: 'Turn an expiring link into a permanent one.' An agent can tell this is a one-way conversion rather than the time-window tweak implied by the sibling 'extend', though the description never names that sibling to make the contrast 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?

Gives clear preconditions (requires a connected account whose plan includes permanent links) and points to get_account for checking slot availability. It does not state when to prefer this over extend or what to do if no slots remain, so exclusions are absent.

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 annotations already declaring the write/non-destructive/open-world profile, the description adds useful behavioral details: pages are served sandboxed on their own link, the public URL is returned, and index.html is required. It still omits auth needs, rate limits, and what happens on republish, but the added context is valuable.

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 purpose and usage, and every sentence earns its place by covering the required file structure, binary assets, return value, and serving behavior. It is appropriately sized with no wasted wording.

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 rich schema (100% coverage), annotations, and an output schema, the description covers the essential call behavior: what it does, required index.html, optional base64 files, and where the content is served. It does not address optional parameters like slug, title, or password, but those are fully documented in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description repeats the files example and says images can go in base64_files, but adds no syntax or format details beyond what the schema provides.

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 ('Put ... online instantly') and resource ('a web page or small static site you created'). It does not distinguish this tool from siblings like upload_file or create_upload_session, so the agent must infer the boundary.

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 when you have a page or site you created, but provides no explicit when-to-use conditions, prerequisites, or alternatives. No guidance on when to choose this over upload_file or create_upload_session is given.

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 mutation profile (readOnlyHint false, idempotentHint true, destructiveHint false). The description adds value beyond them by disclosing the subscription_required error path and the semantics of null as removal rather than clearing a value.

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 dense sentences; the set/remove duality is front-loaded and the prerequisite follows, with no wasted wording.

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 still covers both operation modes, the plan prerequisite, and the failure error. Nothing needed to invoke 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 the baseline is 3. The description restates the null-to-remove behavior already documented in the schema and adds no length or format detail beyond it.

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 (protect/set) and resource (link password) plus the dual mode: set a password or pass null to remove it. This is clearly distinguishable from siblings like delete_link or make_permanent.

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

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

Gives clear context for both use modes (protect vs. remove via null) and a prerequisite (plan must include passwords, else subscription_required). It does not name an alternative tool, but for this unique operation none exists among the 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 declare a non-idempotent, non-destructive write; the description goes well beyond them by disclosing the 20 MB inline limit, the one-time manage_token, the possible "checking"/"publishing"/"unpublished" statuses, and the returned fields. This is exactly the behavioral context an agent needs before calling a write 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?

Front-loaded with the core action and link result, then layered with encoding, rendering, return value, status, and size limit in a dense but waste-free sequence. Every sentence carries actionable 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?

Despite an output schema existing, the description helpfully names the key returns (URL, expires_at, manage_token) and covers limits, status handling, and the sibling for large files. 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 coverage is 100%, so the schema already documents each parameter. The description still adds real meaning beyond it: base64 for binary files, and the rendering semantics of filename extensions (.html becomes a web page, .zip with index.html becomes a website), plus the inline size ceiling.

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?

"Put a file online and get a short public link" states a specific verb and resource, and the description distinguishes this from create_upload_session (bigger files) and get_link (status checks). An agent can tell it apart from its siblings without opening their schemas.

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 routing: use create_upload_session for files above 20 MB, and call get_link when status is "checking"/"publishing". It also notes the manage_token requirement for anonymous callers to check or delete. When-to-use and when-to-use-something-else are both present.

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