JustCopy

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

Goes well beyond the annotations by disclosing that the operation is asynchronous (returns immediately, result via get_site), that it consumes a build credit on paid plans, that it is unavailable on the free plan, and that get_site will report needs_upgrade with an upgradeUrl. This is exactly the cost/async/plan context an agent needs before invoking a mutation.

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

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

Front-loads what the tool does and the examples, then the async behavior, then billing. Four sentences all carry information, though the billing detail is slightly dense and could be tightened.

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 async/polling model plus plan-gating is fully spelled out. Nothing an agent needs in order to call it correctly and interpret the outcome 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 baseline is 3, but the description adds genuine meaning by illustrating what the freeform `request` string should contain (plain-words change instructions) rather than structured fields. `siteId` provenance is already covered in the schema.

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 (changes), resource (an existing website), and clarifies the input modality with three concrete plain-language examples. Clearly distinguishes itself from create_site by scoping to existing sites.

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

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

Explicitly routes the agent: the call returns at once and get_site reports the result, so polling behavior is clear. It also states plan gating (paid plans only after first build). It does not explicitly say 'use create_site for new sites', but the 'existing website' scoping makes that inference easy.

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 supply the generic safety profile (readOnlyHint=false, non-idempotent, non-destructive), while the description adds substantial context the annotations cannot: asynchronous background execution (1-3 min), immediate return with a siteId, quota/cost accounting (3 builds/day, up to 5 sites), built-in auth/data/photo features, and the placeholder behavior for missing facts.

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 purpose is front-loaded in the first clause, followed by example, behavior, async model, and cost. All sentences carry information, though the illustrative example sentence is long and the density is high for a single-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?

Despite an output schema existing, the description still tells the agent the key return value (siteId) and how to poll it, plus the async timing and quota implications. For a background build tool this is exactly the context an agent needs to invoke and follow up 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 at 100% schema coverage, so the schema baseline is 3. The description goes beyond it by explaining what belongs in the description string (business + desired functionality), giving a concrete example, and clarifying that real facts become content while missing ones become marked placeholders.

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 ('Builds a new website or simple web app') plus the exact input modality (plain-language business description). The scope and output are distinct from the sibling tools list_sites/get_site/change_site/publish_site, so an agent can tell it apart without opening any 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?

It routes the agent for follow-up ('get_site reports its progress') and surfaces a real selection constraint (costs one of the day's builds). It does not explicitly say when NOT to use it, e.g. that modifying an existing site should go to change_site instead, so the sibling routing is only partial.

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. The description adds useful behavioral detail: it enumerates the status categories (building, ready, live, needs paid plan) and explains that waitSeconds causes the answer to wait for a running build to finish first. This goes beyond the annotations by disclosing wait semantics and output categories.

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 and front-loads the core purpose before covering the optional waitSeconds behavior. It is appropriately sized for a two-parameter read tool. The first sentence is dense but every element listed corresponds to a meaningful output category.

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 low complexity, full schema coverage, annotations covering the safety profile, and the presence of an output schema, the description is nearly complete. It explains what is returned and the wait behavior. The main missing element is explicit routing guidance relative to sibling tools, but that is a minor gap for a straightforward single-site retrieval 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 100%, so both parameters are already well documented in the schema. The description reinforces waitSeconds by stating that the answer waits up to 20 seconds for a running build to finish, but it adds little beyond what the schema already says. The baseline score of 3 is appropriate when the schema carries the parameter documentation burden.

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 that the tool reports on a single website, enumerating its status, links, builder message, and suggested changes. It implies a read-only retrieval purpose and distinguishes itself from list_sites by focusing on one site. However, it does not explicitly name any sibling tool or contrast its role with alternatives like create_site or publish_site.

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 offers no guidance on when to use this tool versus alternatives such as list_sites or change_site. It only describes what information is returned and the optional wait behavior. There is no mention of prerequisites or contexts that would select this tool over another.

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 usefully adds ordering (newest first) and the shape of each returned item (status, public link), but says nothing about pagination or how the default of 20 relates to the cap of 50.

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 well-formed sentence with zero filler; scope, ordering and returned fields are all 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?

The output schema exists, so return values are already documented, and annotations cover the safety profile. The gap is the undocumented limit parameter and the absence of any pagination context, which matters for a listing 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?

There is one parameter (limit) at 0% schema description coverage, and the description never mentions it, its default of 20, or the maximum of 50. The schema carries type and bounds but the description adds no meaning, leaving the agent to infer the parameter's behavior entirely.

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 (Lists) and resource (websites) plus the scope (signed-in person) and ordering (newest first), so the agent can distinguish it from get_site or create_site. It stops short of explicitly stating the list-vs-single-item distinction, relying on the reader to infer it from the verb.

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 the read scenario (enumerating the signed-in user's sites) but never says when to reach for this versus get_site or when it is not appropriate. No alternatives or exclusions are named.

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

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

Annotations already declare idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond the structured fields: publishing is free on every plan, free sites get a JustCopy badge, and republishing mutates the live site rather than creating a duplicate. It omits auth/permission requirements, which is the only notable gap.

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 core action, then cost/badge, then the optional address format and republish behavior. No sentence is redundant against the schema or annotations.

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. The description covers cost, badge exposure, subdomain semantics, and repeat-publish behavior, which is nearly everything an agent needs. Only permission/authentication expectations are absent.

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, but the description earns extra credit by giving the fully resolved host form (<address>.app.justcopy.ai) and the accepted character set, which the schema's regex pattern does not spell out in words. The siteId parameter is left to the schema, which already points at list_sites or create_site.

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 — 'Puts a built website online at a public link' — and the phrase 'a built website' implicitly separates it from the create_site sibling, which does not imply a pre-existing build artifact. An agent can distinguish publishing from creating or fetching a site without opening another 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?

Usage is only implied: 'Publishing again updates the live site' tells the agent this is repeatable, but no sibling is named and no condition is given for choosing publish_site over change_site or get_site. The guidance is adequate but stops short of explicit when/when-not routing.

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