Agent Genesis Tools

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

With no annotations supplied, the description carries the full burden and does well: it discloses the exact compliance thresholds applied, the return payload (ratio, RGB conversion, AA verdicts, adjustment recommendations), and that the operation is a computation, not a mutation. It does not say what happens on malformed hex input or whether 3-digit shorthand is normalized, which are the remaining behavioral gaps.

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, front-loaded with the computation and thresholds before the usage trigger and the return summary. Dense but every sentence contributes; the only soft spot is the mildly promotional 'Anti-Slop quality standards' clause, which is framing rather than actionable information.

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 pure computation with no output schema, the description covers the algorithm, the pass thresholds, the return contents, and the intended usage moment. An agent has everything needed to call it correctly and interpret the result without further context.

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 both parameters already document accepted formats, examples, and their roles (foreground text/icon vs. background surface). The description adds only the conceptual framing 'foreground text and background colors', so the schema is doing the heavy lifting 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?

States a specific verb ('Computes') and a precise resource ('mathematical WCAG 2.x relative luminance contrast ratio between foreground text and background colors'), then names the concrete output (PASS/FAIL at 4.5:1 and 3.0:1). Nothing about it overlaps with the sibling tools (skills, brand design, codebase graph), so an agent can route unambiguously.

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?

'Call this tool whenever selecting color pairs for UI elements, text, buttons, or badges' gives an explicit trigger condition tied to the agent's task. There is no stated when-not-to-use or named alternative, but no plausible alternative exists among the siblings for this function, so the guidance is effectively complete.

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 burden and does disclose meaningful behavior: it performs an install (a write side effect), returns the full skill markdown plus destination path, and implies placement in the global cache or workspace. It does not say what happens on an unknown skill name or whether an existing skill at the destination is overwritten, which are the remaining gaps for a mutating tool.

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, front-loaded with the action and immediately followed by the trigger condition and the name-resolution fallback. Slight deduction for jargon like 'STOP & EQUIP protocol' and 'dynamically unfreezes', which consume space without adding operational information.

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 tool with no output schema, the description covers the trigger, the name-resolution path, and the return value (markdown plus destination path), so an agent can call it correctly. Missing is failure behavior for an invalid skill name, which matters given the vault reportedly holds 915+ skills.

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 both skill_name and target_path are already documented, including the default destination paths. The description adds only the pointer to list_vault_skills for name resolution, which the schema also mentions, so value beyond the schema is marginal.

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 — unfreezes and installs a specialized skill from the offline vault into the active environment — plus scope (915+ skills) and the returned artifact. It is clearly distinguishable from the sibling list_vault_skills, which only enumerates names.

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 trigger ('whenever a task requires specialized domain knowledge, workflows, or rules ... before writing code') with concrete examples, and names the alternative explicitly: call list_vault_skills first when the skill name is uncertain. When-to-use and fallback routing are both covered.

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 the return shape: the brand's full markdown design tokens, or an index of brands when 'list' is passed. That is the critical behavioral fact for a read-only retrieval tool; permissions, rate limits, or caching are not mentioned but are low-risk for a static local library.

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, front-loaded with the resource and contents before the usage prompt and return format. Some promotional phrasing ('world-class', 'generic AI slop') is expendable but takes only a few words and does reinforce intent.

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-optional-parameter retrieval tool with no output schema, the description supplies everything needed: what is returned, how the parameter changes the return, and the size of the brand library. No important calling detail 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 the baseline is 3, but the description goes one step further by tying the 'list' value to a specific output form ('an index of available brands'), which clarifies the practical effect of the default. It does not add slug-formatting rules or fallback behavior for unknown brands, keeping it just above baseline rather than exceptional.

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 ('Retrieves') and enumerates the exact resource contents: color tokens, typography scales, elevation shadows, and aesthetic rules from 74 named brands. No sibling tool (check_contrast, query_codebase_graph, etc.) overlaps this scope, so an agent can distinguish it immediately.

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 says to call it 'whenever styling user interfaces, web apps, or frontend components', which gives a clear triggering context. It stops short of naming when-not-to-use conditions or pointing at sibling tools such as check_contrast for validating chosen colors after retrieval.

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 behavioral burden. "Inspects" implies a non-mutating read and the return payload (status, node/edge metrics, artifact count, recommended next steps) is spelled out, which is meaningful disclosure; however, it never explicitly guarantees read-only safety, and it does not say what happens when no graph exists yet, which is the key conditional behavior for this tool.

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, front-loaded with what it does, then when to call it, then what it returns. The "up to 80% token reduction" clause is mildly promotional but serves as motivation for calling it first, so it earns its place.

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 optional parameter with no output schema, the description covers purpose, trigger, and return contents, which is enough to call it correctly. The only real gap is the no-graph-exists case, which matters because the description frames the tool as a verification step.

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 repo_path's schema description already explains the absolute/relative path and the current-working-directory default. The description adds nothing about the parameter, so the schema does all the work — the 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?

"Inspects the operational state and artifact health of the Graphify AST knowledge graph for a repository" gives a concrete verb (inspects) and resource (graph status/health), which clearly separates it from a content-query sibling like query_codebase_graph. It never names a sibling explicitly, so differentiation is inferred 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?

"Call this tool before analyzing or refactoring codebases to verify if precomputed dependency graphs ... exist" gives a clear precondition and trigger context. It stops short of naming an alternative tool or stating when to skip it, so there is no explicit exclusion or routing rule.

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 well: it discloses that the vault is offline, contains 915+ skills, avoids bloating token context, and returns name, category, and capability summary. It does not explicitly state read-only behavior, failure modes, or pagination behavior beyond the limit parameter, keeping it below a 5.

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 tightly written sentences with no wasted words. Purpose and sequencing are front-loaded, and the return value note is brief.

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 optional-parameter search/list tool with no output schema and no annotations, the description adequately covers purpose, usage sequencing, token considerations, data source, and return shape. It could be slightly more complete by clarifying behavior when all parameters are empty, but the schema already covers that.

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 the parameters are already fully documented in the schema. The description does not add parameter-level syntax or behavior beyond what the schema provides, 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 states a specific verb and resource: it discovers and searches specialized skills from the offline Skills Vault by keyword or category. It also distinguishes the tool from equip_skill by positioning itself as the discovery step that returns skill names before invocation.

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 says to call this tool first to locate relevant skill names before invoking equip_skill, which gives the agent clear sequencing and names the relevant sibling. No exclusions are given, but the primary when-to-use condition is unambiguous.

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 behavioral burden. It implies a read-only query, discloses output categories ("matched graph nodes, dependency edges, god class rankings, or architectural structure summary"), and flags the token-efficiency benefit, but it never states the prerequisite that the repo must already be indexed into graphify-out/, nor what happens when no graph exists.

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 capabilities before the usage context. The second sentence's use-case framing partially restates the first, but overall density is high with 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 two-parameter query tool with no output schema, the description covers purpose, invocation contexts, and the shape of returned data, which is close to sufficient. The one substantive gap is the unstated requirement that an AST graph be pre-built, something an agent would need to know to avoid a failed call.

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 schema already enumerates every query mode ('summary', 'god_nodes', 'dependencies', 'communities') with definitions. The description's operation list loosely mirrors those modes but adds no format or syntax detail beyond the schema, so 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 names a specific verb and resource ("Queries the codebase AST knowledge graph") and enumerates the distinct operations it supports: symbol lookups, god class identification, dependency tracing, and community cluster search. None of the siblings (check_contrast, equip_skill, get_brand_design, list_vault_skills) operate in this domain, so an agent can select it unambiguously.

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 clear situational triggers — "codebase onboarding, architectural review, or debugging" — and states a motivating condition (avoiding reading massive source files). There are no explicit exclusions or named alternatives, but no sibling offers overlapping capability, so the omission is low-risk.

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