Skip to main content
Glama

fetch_asset

Download a single asset file by direct URL through an unlock ladder, saving it to disk without overwriting, and return its path, content type, and size as JSON.

Instructions

Download a single asset file (image, PDF, font, CSS, any file) from its URL through the same unlock ladder as read_url, save it to disk, and return {path, content_type, bytes} as JSON. Use this for one specific file by its direct URL; to pull a whole page's assets at once use grab_site instead. Saves into out_dir (a relative folder inside the working directory, or SEARCHTS_MCP_OUT_DIR if the user set it) when given, otherwise that folder itself, and never overwrites an existing file. Returns an 'Error: ...' string on failure. Update check: when a newer release exists, a successful result also carries 'update_available' plus, at most once per 24 hours, one line telling the agent. The check is one GET to the GitHub latest release of capad-xyz/searchts, at most once per 24 hours, cached in ~/.searchts/update-check.json, with a searchts User-Agent and nothing about the user. Nothing is installed or changed. SEARCHTS_NO_UPDATE_CHECK=1 turns the check and the note off.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "url": "<url>"
    },
    "name": "fetch_asset"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlYes
out_dirNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.8.0
    • addedInput schema / properties / out_dir / default
      Added value: +""
    • removedInput schema / properties / out_dir / description
      Removed value: -"Directory to save into (optional; defaults to the current directory)."
    • addedInput schema / properties / out_dir / title
      Added value: +"Out Dir"
    • removedInput schema / properties / url / description
      Removed value: -"Direct URL of the asset file to download."
    • addedInput schema / properties / url / title
      Added value: +"Url"
    • addedInput schema / title
      Added value: +"fetch_asset_toolArguments"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "result": {
      +      "title": "Result",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "result"
      +  ],
      +  "title": "fetch_asset_toolOutput",
      +  "type": "object"
      +}
  2. First observedv0.5.1

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the unlock ladder, that it writes to disk, that it never overwrites an existing file, that failures return an 'Error: ...' string, and that a successful call may make one GitHub GET (cached, User-Agent only, nothing installed). Network egress and privacy implications of the update check are spelled out explicitly, which is exactly the kind of context annotations could not supply here.

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

Conciseness3/5

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

The core purpose and the grab_site alternative are front-loaded, which is right. However, the update-check explanation runs four sentences and restates 'at most once per 24 hours' twice, which is disproportionate for an incidental cross-cutting concern on an asset-download tool.

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

Completeness5/5

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

For a 2-parameter tool with an output schema present, the description covers the write destination, overwrite policy, failure representation, and an unexpected network side effect. An agent has everything needed to invoke it correctly and predict the outcome.

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

Parameters4/5

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

Schema coverage is 0%, so the description must compensate, and it largely does for out_dir: it is a relative folder inside the working directory, falls back to SEARCHTS_MCP_OUT_DIR, and existing files are never overwritten. The url parameter is only described as 'its direct URL', leaving format expectations (absolute vs relative, auth) to inference.

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

Purpose5/5

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

States a specific verb and resource ('Download a single asset file... image, PDF, font, CSS, any file') plus the side effect (save to disk) and the return shape {path, content_type, bytes}. It explicitly differentiates itself from the sibling grab_site, so an agent can route 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.

Usage Guidelines5/5

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

Gives an explicit selection rule: 'Use this for one specific file by its direct URL; to pull a whole page's assets at once use grab_site instead.' It also names the escape hatch for the update check (SEARCHTS_NO_UPDATE_CHECK=1), covering both when-to-use and how to suppress a side behavior.

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