UGT: Use the GitHub Thing

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds useful context about what the returned line actually does (installs UGT and wires it to the user's AI apps) and that results vary by platform, which is more than the annotations provide, though it says nothing about caching, rate limits, or version selection.

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?

It is a single sentence, but it is a run-on that strings three ideas together ('installs UGT', 'connects it to their AI apps, UGT for Claude Desktop', 'what each computer runs recipes in'), and the middle appositive is awkwardly placed. The core action is front-loaded, but the phrasing costs 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?

With only one optional parameter, full schema coverage, and an output schema to document the return shape, the description needs only to say what is produced and how the optional parameter behaves — and it does both. The only shortfall is the unclear 'runs recipes in' phrase, which an agent must infer from the output schema.

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 enum of six platform values is fully self-documenting, so baseline 3 applies. The description's 'omit the computer to get every one' merely restates the schema text rather than adding new meaning such as what the no-parameter response looks like.

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 resource: the one-line install command for UGT plus the connection to the user's AI apps (Claude Desktop). The trailing clause 'what each computer runs recipes in' is ambiguous (likely a recipe runtime per platform), but the primary purpose is unmistakable and the sibling tools (get_project, get_recipe, read_recipe_file, search_recipes) operate on entirely different resources, so no confusion arises.

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 only guidance is 'Omit the computer to get every one,' which is already stated verbatim in the schema's parameter description. There is no statement of when to call this versus the sibling tools, no prerequisite context (e.g., whether the user must be on a specific platform or already have an account), and no exclusion 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds behavior beyond that: 'Every GitHub project works with UGT, so the result always says what to do next' — telling the agent there is no unknown-project failure path and that responses carry next-step guidance. It does not discuss latency, caching, or what happens for private or nonexistent repos, which would have pushed this higher.

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 verb and resource before the call trigger. Minor waste in promotional phrasing like 'each verified for one job' and 'what to do next', but nothing is padded to the point of obscuring the point.

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, and the description still usefully characterizes the response as always containing next steps. For a single-parameter, read-only lookup the definition covers purpose, input format, and invocation trigger adequately; only sibling routing is left implicit.

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% and the single 'project' parameter is fully documented in the schema as owner/repo or a GitHub link. The description repeats the same accepted formats without adding syntax, normalization, or edge-case guidance, so the schema does the work and 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?

The description gives a specific verb and resource: 'Get how UGT runs one GitHub project ... the recipes people have shared for it.' The 'recipes' framing implicitly separates it from get_recipe (single recipe) and search_recipes (discovery), but it never names those siblings, so the differentiation is inferential rather than explicit.

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 states a clear trigger: 'Call it whenever the user names a GitHub project they want to use.' That is a usable when-to-use rule. It stops short of naming alternatives (get_recipe, search_recipes) or stating when not to use it, so an agent must still infer the routing for a named recipe versus a named 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, idempotentHint, non-destructive, and closed-world, so safety is covered. The description adds genuine substance beyond that: it discloses that the response includes declared inputs/outputs, persistence effects ('what stays usable after a run'), required settings, external reach with justification, test locations, and every file touched. It omits any mention of error or not-found 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?

Two sentences, front-loaded with the core action and followed by a concrete use case. The enumeration of returned sections is long but each item conveys distinct information, so little is wasted.

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 single-parameter read tool with an output schema and full annotation coverage, the description supplies ample context about what the call yields and when to use it. Only edge-case behavior (missing or private recipes) is unaddressed.

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% and the single parameter already documents its owner/repo/task format with an example, so the schema carries parameter meaning. The description adds nothing about the recipe identifier format, leaving it at the baseline for a fully documented 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?

The description states a specific verb and resource ('Get one recipe in full') and enumerates what the full record contains, so its purpose is clear. It does not explicitly contrast itself with read_recipe_file or search_recipes, so an agent must infer that this returns structured recipe metadata rather than file contents.

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 one clear usage context ('Use it to tell the user exactly what a recipe will do before they run it'), which implies a pre-execution inspection workflow. However, it never states when not to use it or points to siblings like search_recipes for discovery or read_recipe_file for file contents.

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?

The annotations already establish that this is a safe, read-only, idempotent operation. The description adds useful context about inspecting executable recipe content, but does not disclose behavioral details such as size limits, truncation, or handling of unsupported files.

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 compact sentences front-load the operation, scope, examples, and purpose, then provide file-discovery guidance. There is no redundant or unnecessary wording.

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 two-parameter read tool, the description supplies the essential purpose and discovery workflow. Fully documented inputs, comprehensive safety annotations, and an output schema cover the remaining invocation needs.

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%, including the recipe ID format and the requirement to use a path as listed by get_recipe. The description’s filename examples add a little context, but it largely repeats rather than expands the parameter 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?

“Read one of a recipe’s files” gives a specific verb, resource, and scope, while examples such as compose.yaml and recipe.json clarify the available content. Mentioning that get_recipe lists files also distinguishes this content-retrieval tool from its closest sibling.

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 “to see exactly what it runs” supplies a concrete inspection use case, and “get_recipe lists its files” guides agents to the sibling tool for file discovery. It does not explicitly state exclusions or when other siblings are preferable, but the routing guidance is clear.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds domain framing (what a recipe is, that it's verified) but says nothing about result ordering beyond 'newest', pagination, or empty-result behavior. Useful context, but not much behavior beyond the structured fields.

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?

Purpose and usage are front-loaded in the first sentence, which is good. But that sentence is overloaded with example enumerations, and the closing sentence is partly promotional ('shared so the next person gets it fast') rather than operational. Some trimming would sharpen it.

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 two-parameter, zero-required search with an output schema and full annotation coverage, the description supplies enough to call it correctly and know what the results represent. Missing only sibling routing and result-ordering detail, which are minor given the structured data already available.

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% and both parameters are documented in the schema, so the baseline is 3. The description restates the query semantics (what the user wants done vs. project name, omit for newest) without adding matching rules, tokenization, or ranking behavior. It does not touch limit at all, which is fine since the schema handles it.

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 names a concrete verb+resource ('Search' recipes) and scopes it with real examples of the domain (subtitles, CAD, video-to-Markdown, open-source projects from GitHub). It implicitly separates itself from get_recipe/get_project by framing this as discovery rather than direct lookup, though it never names those siblings. The unexplained 'UGT' acronym slightly blunts the opening claim.

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 explicit mode guidance: query by desired outcome, query by project name, or omit the query to list newest recipes. That covers the main call patterns clearly. It stops short of stating when to prefer get_recipe or get_project instead, so the sibling routing is left to inference.

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