TweekIT MCP Server

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

With no annotations provided, the description carries the full behavioral burden. It discloses key behaviors: base64-encoded input requirement, optional resizing/cropping, transparency handling for raster outputs, API key/secret fallback to environment variables, and the return type (Image or File payload). It stops short of detailing error cases or side effects, but for a conversion operation this is reasonably comprehensive.

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 well-structured and front-loaded: it starts with a one-line purpose, then a short capability summary, followed by a clean list of all 15 parameters and a returns clause. For a tool with this many parameters, the length is justified; every sentence serves a purpose and the list format is easily scannable.

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 complexity (15 params, no annotations, no output schema), the description covers the essential context: prerequisites (base64), all parameters with purpose, auth fallback behavior, and return types. It does not elaborate on error responses, but it does mention 'or an error description' in returns. It could also mention when to prefer 'convert_url', but that is already scored under usage guidelines. Overall, it is sufficiently complete for an agent to select and invoke the 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 coverage is 100%, so the baseline is 3. The description adds relational context beyond the schema: it explains how width/height and crop coordinates fit together in the second sentence, and how alpha/bgColor interact for raster formats. While the param list largely mirrors the schema, the opening paragraph adds integrative meaning that helps an agent understand parameter interdependence.

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 opens with 'Convert an uploaded document payload with TweekIT,' which clearly states the verb, resource, and service. It distinguishes itself from the sibling 'convert_url' by explicitly referencing an uploaded payload rather than a URL, making the tool's scope clear even without naming alternatives.

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 via the prerequisite 'The file must already be base64 encoded' and the mention of optional geometry/transparency parameters, but it does not explicitly state when to use this tool versus the sibling 'convert_url'. There are no exclusions or alternative recommendations, so guidance remains implied rather than 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?

With no annotations, the description carries the full burden. It discloses the two-step behavior (fetch then convert), extension inference fallback, API key/secret env var fallbacks, and the return type (Image/File payload or error description). It stops short of noting potential network side effects or failure modes beyond error descriptions, but the key behaviors are transparent.

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 a concise summary and workflow, followed by an organized Args list and a Returns line. Each argument line is brief, but the list is long due to 16 parameters and largely duplicates the schema, which makes the overall docstring somewhat redundant yet still well-structured.

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 complex tool with 16 parameters, no output schema, and no annotations, the description covers the core workflow, authentication via headers/env vars, parameter semantics, and return type. It adequately explains the tool's place relative to `convert` but could expand on failure cases or supported formats; however, it is sufficiently complete for an agent to invoke 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%, so the baseline is 3. The description repeats the parameter list in a docstring format, adding only minor context such as the condition for `inext` ('if it cannot be detected from the URL or response headers'). This provides little additional meaning over the rich schema descriptions.

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 the tool's purpose: 'Download a remote file and convert it with TweekIT in one step.' It uses a specific verb and resource, and the explanation of fetching, inferring extension, and forwarding to `convert` distinguishes it from sibling tools like `convert` and `fetch`.

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 provides clear context: it is a helper that first fetches the URL and then converts, and it instructs 'Supply `fetchHeaders` when the remote resource needs authentication or custom headers.' It does not explicitly state when NOT to use this tool (e.g., for local files use `convert`), but the workflow is clear enough for an agent to infer.

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 annotations provided, the description carries the transparency burden. It discloses read-only retrieval, API key/secret fallback to environment variables, and that the return is a dictionary of formats or an error message. It doesn't cover rate limits or exact error semantics, but for a simple lookup this is adequate.

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 a one-sentence purpose and uses a compact Args/Returns structure. It contains no filler and every section effectively contributes to understanding the 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 a simple 3-parameter lookup tool with a full schema and output schema, the description covers purpose, parameter semantics, auth fallback, and return behavior. It lacks explicit sibling comparisons, but is otherwise contextually sufficient.

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 the schema already documents defaults and environment fallback. The description adds only examples like 'jpg' and 'pdf' and clarifies '*' behavior, which is marginal value over the structured data already available.

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 opening sentence clearly states 'Retrieve a list of supported file formats or map a file extension to its document type,' providing a specific verb and resource. This distinguishes it from sibling conversion tools by focusing on type mapping and supported-format listing rather than conversion.

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 explains the extension argument's optionality and that '*' lists all formats, giving clear operational context. It doesn't explicitly name alternatives or when-not-to-use, but the behavior is clear enough for an agent to select it for mapping or listing document types.

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 annotations, the description carries the full burden and does disclose meaningful behavioral detail: images return as FastMCP Image, PDFs as File, text/JSON as JSON payload. It omits edge cases like redirects or errors, but the included output format details add value beyond the schema.

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 concise and front-loaded, with a bulleted list of return formats. Every sentence adds value and there is no wasted text.

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 single-parameter tool with no output schema, the description adequately covers the main return types. It lacks usage context versus sibling tools and edge-case behavior, but overall it is sufficient for basic invocation.

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 input schema already fully documents the url parameter with 100% coverage. The description adds no additional parameter-specific meaning, so the baseline score of 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 clearly states the tool fetches a URL and returns content, with specific output types. It does not explicitly differentiate from sibling tools like convert_url, but the verb+resource combination makes the purpose evident.

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 guidance is provided on when to use fetch versus the sibling tools (convert_url, search, etc.). The description explains what happens during a fetch but not the selection criteria or alternatives.

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 annotations, the description carries the full burden. It discloses the return structure (list of objects) and best-effort parsing, which is beyond the schema. It notes the HTML endpoint, hinting at potential limitations, but omits details like rate limits or error behavior.

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 three sentences, each earning its place: purpose, return structure, and parsing caveat. It is front-loaded with the core action and contains no filler, making it highly efficient.

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 simple tool with a full output schema and 100% schema description coverage, the description is complete enough. It adds the essential behavioral context of best-effort parsing and return format, though it could mention failure modes or rate limits for full completeness.

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 input schema already describes both parameters with 100% coverage, so the description adds little parameter-specific value. The mention of 'Simple web search' aligns with the query parameter but does not introduce new 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 clearly states the tool performs a web search using DuckDuckGo's HTML endpoint and returns a list of title, url, and snippet objects. This specific verb-resource combination distinguishes it from sibling tools like fetch (retrieve a URL) and convert (transform data).

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 for simple web searches but does not explicitly state when to use it over alternatives like fetch or convert. No exclusions or alternative tools are mentioned, leaving the choice inferred from the tool's name and sibling context.

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