myartefacts

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

With only a title annotation, the description carries the full behavioral burden and does most of it well: it discloses the deferred two-step side effect (the tool only hands back a curl command; publishing happens when curl runs), that no token is needed for the upload, and that the result is printed by curl rather than returned inline. Gaps remain around one-time URL expiry and what happens if the path doesn't exist, which matter for a deferred upload primitive.

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 key mechanism and kept to a tight set of sentences that each carry information. The closing clause about `project_note` is under-explained and costs a bit of clarity, but overall there is little waste.

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 10-parameter tool with no annotations and no output schema, the description covers the essential lifecycle: what it returns (upload_url, curl, slug, share_url), how publishing completes, and how versioning works via slug reuse. It stops short of error/expiry behavior, which is the main residual gap given the absence of structured hints.

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. The description adds a useful framing ("same fields as publish_artifact, minus the contents"), but it also references a `project_note` field that does not exist in the schema (the schema has `project_description`), which slightly muddies rather than clarifies parameter semantics.

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

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

States a specific verb and resource plus the mechanism: publish a file already on disk by getting a one-time `upload_url` and curl command. It explicitly contrasts itself with publish_artifact ("Takes the same fields as publish_artifact, minus the contents"), so the agent can distinguish it from the sibling without opening either 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 an explicit selection rule: "Prefer this over publish_artifact for any file you wrote to disk, and always for large or binary files," plus a sequencing prerequisite (call list_projects first, reuse an existing slug to version). This is exactly the when-to-use / when-to-use-something-else guidance an agent needs.

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 readOnlyHint annotation, it discloses what actually comes back: only the latest version's contents, and only for text formats (HTML, Markdown, SVG, CSV, JSON), which implies binary artifacts return metadata only. It does not state behavior for a missing slug or whether version history is exposed.

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

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

Two sentences, no waste, with the return-content condition stated up front and the usage cue second. Every clause carries information an agent would otherwise have to guess.

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 no output schema and one fully documented parameter, the description covers purpose, return shape, and intended use well enough to call correctly. Only error/miss behavior for an invalid slug is unaddressed, which is minor for a read 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?

One required parameter with full schema description coverage, so the schema already carries the semantics. The description's 'by slug' restates rather than enriches the parameter — no format, case-sensitivity, or lookup-failure behavior is added. 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?

Specific verb and resource: 'Get one artifact by slug', with the added scope that latest-version contents are included for text types. This implicitly separates it from list_artifacts and search_artifacts, but it never names those siblings, so the differentiation is left to inference.

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 concrete call context: 'Use it to read earlier work before revising it', which anchors it in the revise loop alongside update_artifact. It offers no explicit exclusions or pointer to the list/search siblings for discovery-style lookups.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds genuinely useful behavior — default ordering and that a project filter recursively includes subprojects — but says nothing about pagination, total counts, or what a result entry looks like.

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 tightly-packed sentence with ordering and filters front-loaded; no filler or redundant restatement of 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 no output schema and all five params fully described in the schema, the definition is nearly self-sufficient for a read-only list. The remaining gap is minor: no hint about result shape or how pagination/limits interact across pages.

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 baseline is 3. The description restates the filterable parameters and adds the subproject-inclusion nuance for project, but no format or semantics beyond 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 and resource ('List the user's artifacts') plus ordering ('newest first') and the filterable dimensions. It does not, however, distinguish itself from the sibling search_artifacts, which an agent could plausibly pick for the same goal.

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 by the presence of optional filters; there is no explicit statement of when to use this listing tool versus search_artifacts or list_projects. No exclusions or prerequisites are 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?

readOnlyHint=true already establishes the safety profile, so the description only needs to add behavior — and it does, disclosing that the result is recursive (nested ones included) and annotated with each project's purpose. It stops short of saying whether the list is paginated, ordered, or scoped to one workspace, which is the remaining 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?

Two sentences, no filler. The output shape comes first and the call-site guidance second, which matches the order an agent needs them in.

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 no output schema and no parameters, the description carries the whole burden of explaining what comes back, and it does: nested projects, each with its purpose. For a zero-argument read tool this is complete and correct.

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. Baseline 4 applies; the description correctly spends no words restating an empty 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 and resource ("List the user's projects") plus two scope details that matter: nested projects are included, and each entry carries a description of its purpose. That is enough to distinguish it from list_artifacts and the other siblings without opening a 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 tells the agent when to call it ("before publishing to choose the `project` path") and then prescribes the decision rule for the result: prefer the most specific existing project, and create a subproject like "RentOS/Backlinks" rather than a new top-level one. That is when-to-use plus how-to-act, not just context.

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 meaningful annotations beyond the title, the description carries the behavioral burden well: it explains that reusing slug publishes a new version at the same URL, that share creates a public link anyone can view, and that share_note/project_note may appear in the answer. It does not cover permission requirements, overwrite edge cases, or rate limits, so it is strong but not exhaustive.

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 and dense with useful routing information. Every sentence contributes either scope, an alternative, or a parameter behavior, with no wasted text despite covering an 11-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?

For an 11-parameter mutation tool with no output schema, the description covers the main invocation choices, alternatives, versioning, sharing, and project filing. It is slightly incomplete on return behavior and permission or failure semantics, but it provides enough context for an agent to call 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 already 100%, so the baseline is 3, but the description adds useful meaning beyond the schema: content-versus-base64 selection for text versus binary, slug as a stable version identifier, share as public-link generation, and project filing via list_projects. It does not elaborate on several other documented parameters, which keeps it from a 5.

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

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

The description states a specific verb and resource: publishing a file into the user's myartefacts dump by pasting its contents. It also distinguishes this tool from the sibling create_upload_url for files already on disk, so an agent can tell when this tool is the right choice.

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 names the alternative create_upload_url and the condition that selects it: files already on disk. It also gives clear guidance for using content versus content_base64, reusing slug for a new version, enabling share for public links, and calling list_projects before filing into a project.

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, so the safety profile is covered. The description adds one useful behavioral fact — archived artifacts are included in results — but says nothing about match semantics (substring vs fuzzy), result ordering, or that the limit caps at 100.

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, and the searchable-field enumeration is front-loaded ahead of the archived-scope caveat.

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 two-parameter read-only tool with full schema coverage, no output schema, and readOnly annotations, this is close to sufficient. The remaining gap is result behavior — relevance ordering and pagination beyond the limit parameter — which the agent would have to discover empirically.

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 baseline would be 3, but the description earns extra credit by naming the fields actually searched (title, slug, summary, prompt, project, agent, kind), which tells the agent far more about what 'query' matches than the schema's generic 'Words to look for'.

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 (search) and resource (user's artifacts) and enumerates the searchable fields, which is more than a restatement of the name. It does not explicitly distinguish itself from the sibling list_artifacts, leaving the agent to infer the search-vs-enumerate split.

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: the presence of a free-text query and the note that archived artifacts are included suggest this is the keyword-retrieval path, but nothing says when to prefer list_artifacts or how to reach a specific artifact via get_artifact.

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?

Only a title annotation exists, so the description carries the burden and does well: it discloses version semantics (new version, same slug/URL), the metadata-only mode, and the not-found failure. It stops short of saying what is returned (new version identifier, URL) or whether the new version goes live immediately.

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 sentences, zero filler, and the primary action is front-loaded before the conditional mode and the sibling alternative. The parenthetical parameter list is compact and functional rather than 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 11 parameters, no output schema, and no annotations, the description covers the mutation model, failure mode, and look-alike tool well. It leaves return shape and post-publish visibility unspecified, which matters for a tool whose output is a shareable link, but nothing needed 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 baseline is 3; the description earns a bump by describing cross-parameter behavior the schema cannot — the content/content_base64 presence toggling between 'new version' and 'details only' mode, and the grouping of metadata fields (title, project, summary, prompt, share) that survive that toggle.

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 ('Publish a new version of an artifact') and the key invariant (slug and URL preserved), which is exactly what distinguishes it from publish_artifact. An agent can tell it apart from its siblings 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?

Gives explicit routing: omit content/content_base64 to only change metadata (with the concrete use case of moving an artifact between projects), and 'use publish_artifact for new work' for the alternative. It also names the failure condition (no artifact with that slug), so the agent knows when not to call it.

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