shortcut-forge

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

No annotations are provided, so the description carries the full burden and does substantial work: it discloses the write artifact (.shortcut file), the platform constraint on signing (macOS), the lint-pass behavior with 'fix all errors' guidance, and the return payload (paths, action count, lint findings). It stops short of covering overwrite behavior on an existing output_path or any credential requirements for signing.

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?

Four short sentences, front-loaded with the core action and the spec shape, then reference pointer, then signing condition, then return values. Only blemish is a stray line break mid-sentence that slightly fragments the second thought; there is no 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?

Returns are described, which compensates for the absent output schema, and the required spec parameter is illustrated. But for a mutating build tool with 0% schema coverage and no annotations, the missing semantics for sign_mode and output_path plus the lack of overwrite/error behavior leave real gaps.

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 0%, so the description must compensate; it explains the required spec object's top-level keys and the sign flag's macOS condition. However, sign_mode (a free-form string defaulting to "anyone" with no enum or description) and output_path are left entirely undefined, which is a meaningful gap on a signing-related parameter.

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+resource: builds a .shortcut file from a JSON spec and lints it, with the spec shape sketched inline ({"name": ..., "actions": [...]}). An agent can distinguish it from shortcut_lint or shortcut_sign, though the fact that linting is bundled here (rather than deferring to the sibling shortcut_lint) is only implicit.

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 real conditional guidance: set sign=true on macOS for an importable signed file, and consult shortcut_reference(topic="spec") for step types. It does not say when to choose this over shortcut_from_template or the standalone shortcut_lint/shortcut_sign siblings, so no exclusions are 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?

No annotations are provided, so the description carries the full burden. It does not disclose whether generation writes a file, what output_path does, what signing means or when it is required, or what side effects occur. Only the template/config behavior is partially described.

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 short, front-loaded, and free of filler. Its brevity is appropriate, though the space saved is not used to cover important missing parameter semantics.

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 generation tool with five parameters, no annotations, no output schema, and 0% schema description coverage, the description is too thin. Missing sign, sign_mode, and output_path semantics leave an agent unable to call it correctly beyond the simplest template-only case.

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%, and the description only covers template and config. The sign, sign_mode, and output_path parameters are completely undocumented in both schema and description, leaving three of five parameters without semantic guidance.

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: 'Generate a shortcut from a ready-made template.' That distinguishes it reasonably well from sibling shortcut_build by implying template-based rather than freeform construction, though it does not explicitly contrast the two.

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 gives useful context for using config (omit it to get the example) and points to shortcut_reference for template config shapes. However, it does not say when to choose this over shortcut_build, nor does it mention any prerequisites or conditions for template use.

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?

No annotations, so the description carries the full burden. 'Return ... outline' implies a read-only operation and 'unsigned' connotes a scope limit, adding some value, but it says nothing about error behavior for signed/missing files, or whether it parses or just dumps structure.

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 sentence with no filler. Terse to the point of under-specification, but structurally clean.

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?

Output schema exists so return values needn't be described, and the operation is simple with one param. Still, with zero annotation coverage and an undocumented path parameter, the definition leaves the agent to infer the file-path semantics on its own.

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 0% and the only parameter ('path') is undocumented in both schema and description. The description never mentions what the path points to or what format it takes, so it adds no meaning beyond guessing from the tool name.

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 (return) and resource (indented, human-readable outline of an unsigned .shortcut file). The 'unsigned' qualifier implicitly separates it from shortcut_sign/lint siblings, though no sibling is named.

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 explicit when-to-use, prerequisites, or alternatives. The word 'unsigned' hints that signed files are out of scope but never states what to do with them or why one would inspect rather than lint.

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 at all, the description must carry the full behavioral burden; it does disclose the per-mode return content and the conditional 'signed download link if published'. However, it never states that this is a read-only browse operation, whether auth is required for download links, or how large the list result can be.

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 short blocks, front-loaded with the resource and its scope, then the mode switch. Efficient overall, though the mid-sentence line breaks and the parenthetical '(or template config)' make it slightly denser than necessary.

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?

There is no output schema, so the description is the only source of return-value information; it covers detail mode (meta, spec, download link) but says nothing about the shape of list results, result limits, or pagination. Adequate to call correctly, incomplete for interpreting results.

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 0%, so the description has to compensate, and it largely does: `query` is defined as matching name/description/tags, and `slug` is defined as switching from list mode to detail mode with a specific payload. It adds real meaning over the bare, undocumented schema properties.

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 ('Browse the community shortcut library') and gives concrete content scope (20+ ready shortcuts across categories). It implies a clear separation from siblings like shortcut_build/shortcut_inspect, but never names an alternative, so it stays short of a full 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?

Explicitly defines the two modes: no slug → list matching entries, with slug → fetch that entry's meta/spec/download link. That is clear operational context, but there is no statement about when to prefer a sibling tool (e.g. shortcut_inspect or shortcut_from_template) instead.

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 and no output schema, the description carries the full disclosure burden. It does not say whether linting is read-only or rewrites the file, what a result looks like (violation list vs pass/fail), or whether the referenced rules can be suppressed; only the rule-ID range hints at 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?

One front-loaded sentence with zero filler; the rule range is parenthetical and secondary in emphasis.

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 tool with no annotations, no output schema, and an undocumented parameter, the definition leaves key questions open: is it read-only, does it modify or emit anything, what does a failure report look like, and are there prerequisites (e.g., platform or dependency on shortcut_reference rule data).

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 0% and the single 'path' parameter is undocumented in the schema. The description partially compensates by implying the path must point to an unsigned .shortcut file, but adds no format, relative-vs-absolute, or validation details.

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 (lint) and resource (unsigned .shortcut file) plus the rule set (SF000-SF013), which lets an agent distinguish it from shortcut_build and shortcut_sign. It does not explicitly separate itself from the closest sibling, shortcut_inspect, leaving mild ambiguity between 'lint' and 'inspect'.

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 word 'unsigned' implies a precondition (lint before signing), which is useful implicit usage context. However, nothing states when to prefer shortcut_inspect, shortcut_reference, or shortcut_sign instead, and no exclusions 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?

No annotations are provided, so the description carries the burden. It does convey that the tool only produces text (no mutation, no side effects implied by 'Return a copy-paste system prompt'), but says nothing about how the prompt is tailored, whether it varies, or what triggers different output.

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 sentence with the verb and outcome up front and no filler. Nothing could be removed without losing meaning.

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 and no parameters, the description need only establish intent, which it does. A short note on what the generated prompt targets (spec-writing) is given; the only minor gap is any hint about how the prompt is customized.

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 of 4 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: it returns a copy-paste system prompt for teaching chatbots to write specs. That is clearly distinct from the sibling tools (build, inspect, sign, lint), though the description doesn't name a sibling to differentiate against explicitly.

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 — call it when you want a prompt to hand to another LLM — but there is no explicit statement of when to use this versus e.g. shortcut_reference or shortcut_build, and no exclusions or prerequisites.

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 disclosure burden. It does reveal a meaningful side effect — that the emitted manifest injects spec.update_manifest into the shortcut, changing its runtime update behavior — but says nothing about whether existing output files are overwritten, where files are written, required signing credentials, or what is returned.

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 short paragraphs, front-loaded with the verb chain and the outcome. Dense and largely waste-free, though the hosting sentence drifts slightly into deployment advice rather than tool contract.

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 5-parameter mutation tool with a nested `spec` object, no annotations and no output schema, the description leaves major gaps: the two output files are never named, output_dir is unexplained, and the return value/error modes are unknown. It is not sufficient for an agent to call this correctly without reading the schema or guessing.

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 0% across 5 parameters, so the description must compensate and only partially does. It clarifies `version` (must be bumped per release), `base_url` (hosting location) and the `spec` mutation via spec.update_manifest, but `notes` and especially `output_dir` — which determines where the two files land — are never explained.

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 compound action (build + sign + write manifest.json) with a stated goal (self-updating installed copies), which is distinguishable from shortcut_build and shortcut_sign as the end-to-end publish step. It never explicitly says it subsumes those siblings, so the differentiation is implicit rather than stated.

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?

Offers real operational guidance: host the two output files at base_url (GitHub raw/Pages/S3) and bump `version` for every release. It gives no guidance on when to choose this over calling shortcut_build and shortcut_sign separately, and no prerequisites or exclusions.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It implies a safe read-only reference lookup and lists topics, but does not explicitly state read-only behavior, permissions, or rate limits. For a low-risk docs tool this is adequate but not rich.

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 two compact sentences with zero waste. The purpose is front-loaded and the topic list follows immediately.

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 optional parameter and an output schema present, the description provides enough to call the tool correctly by listing topics. It stops short of explaining how topics map to results or when to prefer this over siblings, but the output schema reduces the need to describe return values.

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%, so the description must compensate. It does enumerate valid topic values (spec, pitfalls, lint-rules, health-types, templates, library, ios27), which is useful, but it does not explain what each topic returns or note the default value beyond what the schema shows.

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 it provides documentation for building shortcuts and enumerates topic areas, making the resource clear. It does not explicitly differentiate itself from sibling tools like shortcut_llm_prompt or shortcut_build, but the topic list gives enough specificity to distinguish a reference lookup.

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?

There is no explicit guidance on when to use this tool versus alternatives such as shortcut_llm_prompt or shortcut_build. The phrase 'Docs for building shortcuts' implies a reference use case, but no conditions or exclusions are 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?

No annotations are provided, so the description carries the full behavioral burden. It mentions the macOS CLI dependency and signing purpose, but does not disclose side effects, permissions required, overwrite behavior for output_path, or what happens to the input file.

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 two concise sentences, front-loaded with the core action and purpose. Every sentence adds relevant context without 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 3-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description is too sparse. It leaves key behavioral and parameter details unexplained, so an agent would need to infer how 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 description coverage is 0%, so the description must compensate. It only names two mode values ('anyone | people-who-know-me') and does not explain the required path parameter or the output_path parameter, leaving most parameters undocumented.

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: sign a .shortcut using the macOS shortcuts CLI, with a clear purpose of enabling iOS import. It does not explicitly distinguish itself from siblings like shortcut_submit or shortcut_publish, so it falls short of full sibling differentiation.

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 phrase 'so iOS can import it' implies when to use this tool, but there is no explicit guidance on alternatives, prerequisites, or when not to use it. The mode options are named but not explained in terms of usage conditions.

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 must carry the burden. It usefully clarifies that it does NOT actually open the PR but returns the git/gh commands to do so, and that it validates and lints. However, it omits auth requirements, whether spec/metadata are mutated or just checked, and return details.

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 core action and followed by the verification note. Efficient, though the out-of-schema `verified_on` reference undermines clarity.

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 8-param, 6-required tool with a nested spec object, zero schema descriptions, and no output schema, the description is thin on parameter meaning. It also references a field (`verified_on`) absent from the schema, which will confuse an agent trying to satisfy required inputs.

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 0% across 8 parameters, so the description must compensate. It mentions spec and metadata vaguely, and even references a `verified_on` field that is not in the schema, while leaving slug, name, author, category, tags, description, and description_ko unexplained.

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: packages a shortcut for a named library, validates/lints, and returns files plus git/gh commands. It distinguishes the workflow but does not differentiate from siblings like shortcut_publish or shortcut_lint, which overlap in scope.

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?

Only guidance is to encourage the user to run it on their iPhone first and fill `verified_on`, which is a helpful workflow note but not a when/when-not comparison. It never states when to choose this over shortcut_publish or shortcut_lint.

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