Identity Forge MCP

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

With no annotations, the description takes full responsibility and excels: it discloses destructive behavior ('overwrites live brand state without asking'), audit trail ('mints a version'), auth scope ('kits:write'), and error semantics (409, 403). This is exemplary transparency for a mutation 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?

The description is long but every sentence earns its place: purpose, axis behavior, project/kit independence, pin rationale, recordId warning, conflict rules, 403 edge case, and side effects. It is front-loaded with the core action and contains 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?

For a complex mutation tool with no annotations and no output schema, this description is remarkably complete. It covers purpose, usage, safety, error conditions, auth, and param semantics, even explaining upgrade paths and version minting – fully sufficient for safe and correct 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?

Despite 100% schema coverage, the description adds significant meaning: it explains why recordId must be a permanent id (slugs are mutable), how single-value axes conflict vs pageRecipe accumulating, and the purpose of replace for drifted revisions. This goes beyond 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 'Put one catalogue record onto a brand project alongside its design kit' – a specific verb, resource, and outcome. It explicitly says 'One tool for all three axes' and differentiates layer composition from siblings like get_brand_layers and remove_brand_layer.

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?

Provides explicit usage guidance: 'One tool for all three axes: pass axis to say which' and explains when to use replace (conflict or drifted revision) and when not to (Pro/403). It also references get_brand_layers to explain the pin behavior, giving clear context for when this tool is appropriate.

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 full burden of behavioral disclosure. It reveals the dependency on kit resolution rules, the entitlement requirement for Pro catalog kits, the 'kits:write' OAuth scope, and that variations are hidden from the client until share_brand_project is called. This goes well beyond a basic 'adds a variation' statement.

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: the first states the operation, the second gives usage guidance and rationale, the third covers prerequisites, visibility, and authorization. It is front-loaded with the core message and contains zero 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?

The description is highly complete for a creation tool: it specifies the action, when to call, prerequisites, visibility semantics, and required scope. The only gap is the lack of any mention of the return value or response structure, which is relevant since there is no output schema. Still, this is a minor omission given the otherwise thorough 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 coverage is 100%, so the schema already documents each parameter. The description adds value by explaining the kit's resolvability requirement and how the optional fields (brandName, domain, label, notes) function as a coherent proposal set. It also hints at the usage pattern (four or five times with contrasting kits), enriching the meaning of label and notes.

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 action ('Attach one brand proposal to a project') and enumerates the components (kit plus optional brand name, domain, label, notes). It distinguishes this from sibling tools like update_brand_variation, remove_brand_variation, and share_brand_project by focusing on the act of attaching a new variation.

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?

Explicit usage guidance is provided: call it four or five times per project with deliberately contrasting kits, and the rationale for that approach. It also specifies prerequisites (kit must be resolvable, Pro catalog kits need an entitled key) and when variations become visible (only after calling share_brand_project), giving clear context for when to use this tool versus 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 idempotency semantics ('identical data again returns the same row; reusing an id with changed data returns a conflict'), the required 'naming:write scope,' and that it 'spends no AI credits.' This is rich behavioral context beyond what annotations could provide.

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 four sentences, each adding value: purpose, relationship to generate_names, idempotency behavior, and auth requirement. There is no filler or repetition of schema fields, making it appropriately sized and front-loaded.

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?

The description covers the tool's purpose, usage context, idempotency, and auth requirement, which is sufficient for an agent to select and invoke it. However, with no output schema, it could optionally elaborate on the success response format beyond conflict/duplicate cases, so I score 4 rather than 5.

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 baseline is 3. The description adds meaningful semantics for the candidateId parameter by explaining duplicate vs conflict behavior in concrete terms, which is not fully captured in the schema's brief idempotency note. This extra detail justifies a 4.

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 uses the specific verb 'persist' and clearly identifies the resource ('names...onto the durable project board'). It distinguishes from sibling generate_names by stating it 'stores names rather than authoring them,' which satisfies 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 description explicitly positions this tool as 'the free counterpart to generate_names,' clarifying when to use it (when names are already produced) versus when to use generate_names (authoring new names). This gives the agent clear guidance on selecting the correct tool.

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 full burden and does so thoroughly: it discloses conflict detection and the write-nothing-on-conflict behavior, names the destructive consequences of force, explains preview as a no-write dry run, guarantees no partial application, and clarifies version null semantics and Pro kit 403 errors. This far exceeds the minimum required for behavioral disclosure.

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 long but every sentence carries substantive behavioral information, and it is front-loaded with the core action and outputs. It could be improved by using bullet points or headings for conflict, preview, and stamp semantics, but the density is justified by the tool's complexity and safety implications.

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 tool's complexity, the absence of annotations, and the absence of an output schema, the description is exceptionally complete. It covers what files are written, conflict handling, error responses, the preview plan, the force destructive path, atomicity, stamp behavior, version interpretation, and access restrictions. An agent has enough context to select and invoke this tool safely without further documentation.

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 each parameter already has a detailed description, so the baseline is 3. While the tool description adds conflict-related context around force and preview, these are largely repeated in the schema parameter descriptions. No parameter meaning is significantly enhanced beyond the 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 leads with a specific verb and resource: 'Write a design kit into a project on disk' and enumerates exactly what gets written (DESIGN.md, tokens file, identityforge.json). This clearly distinguishes it from siblings like get_design_md and get_tokens, which only inspect without writing.

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 states 'This is the only tool here that touches the filesystem' and advises calling it 'once the user has settled on a kit', while naming the alternatives 'get_design_md and get_tokens inspect a kit without writing'. This gives clear when-to-use and alternative guidance.

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 exceeds it: it discloses read-only behavior, that it writes nothing and touches no file, the three independent movement types and their meanings, null-versus-false semantics, inclusion of diff results, artifact hashing, and graceful degradation on missing keys/Pro gates. This is far beyond typical transparency.

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?

Despite being long, every sentence earns its place: primary action, alternative justification, three-movement breakdown, null semantics, diff inclusion, hashing, safety, and degradation. The core purpose is front-loaded, and the density is warranted for the tool's complexity.

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 no output schema, the description fully explains return fields, edge cases (null values, missing keys, Pro gates), and practical implications. It makes the tool actionable without needing additional external knowledge, and it clearly separates concerns like serializer-only changes versus contract changes.

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 schema already covers the only parameter (dir) with 100% coverage, including default and path meaning. The description adds context about the stamp holding kit/version, but does not add parameter-level syntax or format beyond the schema, so baseline 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 opens with a specific verb+resource ('Read the identityforge.json stamp in a project on disk and report what has moved') and immediately distinguishes the tool from diff_kit_versions by noting it takes no kit and no version. The title also reinforces the purpose as a question, making the tool's unique role clear.

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 when to use this tool ('returning to a project') and names the alternative (diff_kit_versions), explaining why this avoids 'reconstructing the arguments' by hand. It also states it is safe to call at the start of any session, providing clear context for when it should be preferred.

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 of behavioral disclosure. It excels by explaining that evidence is reported independently rather than collapsed into a verdict, that lack of DNS does not mean unregistered, that results are a snapshot with no reservation, and that a domain can be taken between call and checkout. It also discloses the required naming:read scope, which is valuable beyond schema info.

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 compact but information-dense. It front-loads the core purpose and scope ('up to 20 bare domains') and then packs essential caveats, alternatives, and auth requirements into every sentence without fluff or repetition.

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 absence of an output schema and annotations, the description does an excellent job of setting expectations: it lists the four evidence sources, explains the separate reporting model, warns about snapshot semantics, names the auth scope, and points to the alternative tool. This is sufficient for an agent to decide when and how to 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 description coverage is 100%, and each parameter already has a meaningful schema description. The tool description adds some context—e.g., 'optional search results showing who else already occupies the name' and 'requires the naming:read scope'—but it mostly reinforces what the schema states. Baseline 3 is appropriate because the schema does the heavy lifting.

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 a specific verb and resource: 'Check up to 20 bare domains and return four independent kinds of evidence.' It enumerates the exact evidence sources (RDAP, DNS, Cloudflare Registrar, optional search results) and explicitly distinguishes itself from the sibling tool search_name_evidence, making its purpose unmistakable.

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 usage guidance: it is for checking specific domains, not for broader name research, and it explicitly directs users to search_name_evidence for non-domain-specific research. It also clarifies when to enable optional search results via includeSerp ('finalist collision research') and when registrar checks might be disabled.

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?

Even without annotations, the description discloses key behavioral traits: it requires the 'kits:write' scope, it is non-idempotent (implied by 'avoid making a second project'), and it has no client-visible effect on its own. This goes beyond basic semantics and helps the agent understand side effects and prerequisites.

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 four sentences, each with a distinct purpose: core definition, workflow sequence, caveat about client visibility, and duplicate-avoidance guidance. No filler or redundancy; information is front-loaded with the primary action.

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 that is one step in a larger workflow, the description includes all necessary context: prerequisites, next steps, scope requirement, and the fact that the creation alone is insufficient. With only two parameters fully described in the schema and no output schema, the description covers the operational context comprehensively.

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 provides 100% description coverage for both parameters (name and brief). The tool description does not add additional parameter-level meaning beyond the schema, so the baseline 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 uses a specific verb 'Create' and resource 'container that holds brand variations and the client share link', which precisely defines the tool's role. It clearly distinguishes itself from siblings by framing it as the first of three steps (with add_brand_variation and share_brand_project), leaving no ambiguity about what this tool does.

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 states when to use it ('Do this once per client brief'), what to do next ('attach several directions with add_brand_variation and send the client a link with share_brand_project'), and a crucial precondition ('Call list_brand_projects first to avoid making a second project'). This is strong guidance with concrete alternatives and sequence.

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?

Even without annotations, the description fully discloses behavioral traits: the created board is durable, persists kanban/research/ledger across sessions, returns an id, and requires naming:write scope while spending no AI credits. This goes well beyond the structured 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 dense but every sentence earns its place: purpose, usage guardrail, persistence semantics, prerequisite call, parameter guidance, and side effects. It is front-loaded with the core action and returns an id 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?

Given the tool's moderate complexity, the description covers creation, reuse, parameter relevance, auth scope, cost behavior, and persistence. It also discloses the return value (id), compensating for the lack of an 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 coverage is 100% with descriptions for all three parameters. The description adds extra meaning by emphasizing that the description field should contain the real brief because generation quality depends on it, and by clarifying the default TLDs indirectly. This adds value beyond the 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: 'Create one durable, project-owned naming board and return its id.' It clearly distinguishes this tool from siblings like list_naming_projects and generate_names by focusing on the creation of a persistent project entity.

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?

Explicit guidance is given: call list_naming_projects first, reuse existing boards, create only once per real naming brief, and write the full brief into the description field. It also states when not to use it ('never once per generation run') and mentions the required naming:write scope.

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 full burden and does so admirably. It discloses that the result is always PRIVATE, that this tool cannot publish, that forking Pro kits needs an entitled key, and that it requires the kits:write scope, including a hint about regenerating the key on a 403. This goes far beyond what annotations would typically provide.

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 a dense paragraph of five sentences. Every sentence carries substantive guidance (mode selection, fork vs. scratch, privacy, entitlement, alternative tool, auth scope). It is longer than the two-sentence ideal but justified by tool complexity; no filler or redundancy is evident.

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 tool's complexity (4 params, nested objects, no annotations, no output schema), the description covers all essential context: purpose, two usage modes, when to choose each, privacy/publishing behavior, Pro entitlement, auth scope, and a sibling alternative. It is complete enough for an agent to select and invoke the tool 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% and the schemas already contain detailed descriptions, so the baseline is 3. The description adds meaningful guidance above that by explaining the relationship between `base` and `overrides` (fork inherits a coherent system, you only state differences) and the privacy implication (always PRIVATE). This lifts it above baseline, though the schema already does most of the heavy lifting.

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 a specific verb+resource ('Author a new design kit') and clearly distinguishes two modes (from scratch via `kit` or forking via `base`). It also differentiates from sibling `remix_theme`, explicitly saying to use that for quick variations.

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?

Provides explicit when-to-use guidance: 'Use `base` whenever a catalog kit is close to what you want' and 'Use remix_theme instead when you want several quick variations off one direction.' Also clarifies the trade-off between forking and authoring from scratch, plus the privacy/publish limitation.

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 full burden. It transparently discloses the permanent destructive nature, the hard requirement for confirm: true, the 409 conflict behavior, and the required OAuth scope. This gives the agent a complete picture of consequences and preconditions.

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, each earning its place: purpose, confirmation requirement, and error scenario/auth scope. It is front-loaded with the verb and object, making it immediately clear what the tool does. No redundant or generic 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?

For a destructive delete tool with no output schema and no annotations, the description covers all essential context: permanence, confirm flag, conflict resolution, and auth. It is sufficiently complete for an agent to select and invoke the tool safely.

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 baseline is 3. The description adds value by emphasizing that confirm must be exactly true and why, which reinforces the schema. It does not need to add syntax details since the schema already documents both parameters well, but the extra cautionary note justifies a 4.

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 action ('Permanently delete') and the resource ('one of your saved design kits'). It distinguishes this from sibling tools by specifying the destructive nature and requiring confirmation, which sets it apart from update/remix tools.

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 on when to use the tool (deleting a kit) and prerequisites (kits:write scope, confirm: true). It also explains a key exclusion: kits referenced by a brand project are refused, prompting the user to retire references first. However, it does not explicitly name alternatives or broader when-not-to-use cases.

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 full burden and does well: it explains that the tool is owner-scoped and nothing is redacted, and details how variation edits are represented ('variations.<id>.<field>' rather than wholesale swap). It also mentions the kits:read permission. This adds meaningful behavioral context beyond the basic purpose.

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 compact and well-organized: it opens with the core purpose, then gives usage guidance, then adds scope and variation-format context, and finally states the required permission. Every sentence earns its place without redundancy or fluff.

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?

The description covers the key aspects needed for selection and invocation: what it does, how to use the from parameter, owner-scoping, variation edit format, and required permission. It lacks a full description of the overall output structure, but given the absence of an output schema, the provided hints are reasonably sufficient for a diff 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?

The schema already covers all 3 parameters with 100% description coverage. The tool description adds extra meaning, particularly the 'Pass `from` alone' behavior for comparing against the current version, which clarifies the interplay between `from` and `to`. This goes beyond the schema's individual field 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: 'What changed between two versions of a brand project.' It specifies the resource (brand project versions) and the action (diff), and distinguishes itself from sibling tools like diff_kit_versions and get_brand_project_version by focusing on brand projects and comparing two versions.

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 a clear usage pattern: 'Pass `from` alone to compare against the current version.' This tells the agent exactly when and how to use the tool. It also mentions scope ('Owner-scoped') and the required permission ('Needs kits:read'). It does not explicitly name alternatives, but the context is clear enough.

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 full burden and excels. It discloses output structure, the effect of omitting `from` or `to`, that it reports mechanical changes without judging their significance, and detailed redaction behavior for unauthorized Pro kits (including the exact shape of redacted objects and counts). It even mentions the required `kits:read` permission. This is exemplary transparency.

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 longer than average, but every sentence earns its place: it front-loads the core result, then guides usage, then covers edge cases and permissions. There is zero fluff or repetition; density of useful information is high.

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 output schema and no annotations, the description successfully covers purpose, output shape, usage patterns, permission requirements, and a nuanced redaction case. An agent has enough context to decide when to call it and what to expect from the response, even without an 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 coverage is 100%, so the baseline is 3, but the description adds significant value beyond the schema. It explains the semantic distinction between passing `from` alone versus both bounds, ties `from` to the version recorded in identityforge.json, and explains how redaction affects parameter output. This goes beyond the schema's terse parameter 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 starts with a concrete, specific verb ('diff') and resource ('two versions of a kit'), then enumerates exactly what the output contains: paths with old/new values, CSS custom properties, and a mechanical summary. It clearly distinguishes itself from siblings like diff_brand_project_versions by focusing on kits and even contrasts with reading DESIGN.md. This is a model of purpose clarity.

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 explicitly says 'This is the tool for taking a brand change into a codebase' and explains the common pattern of passing `from` alone to compare against the current version. It also warns against relying on re-reading DESIGN.md as an alternative. However, it does not name specific sibling tools (e.g., get_kit_version, diff_brand_project_versions) or explicitly say 'use X instead,' so it stops short of full alternative differentiation.

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 discloses read-only behavior ('read-only, mints no version, writes nothing'), required scopes ('kits:read'), owner-scoping, conflict-resolution rules, and specific non-error outcomes. This gives agents a strong behavioral model without needing external annotation signals.

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 the core value proposition and uses a single dense paragraph. Every sentence conveys meaningful information, but the length is slightly over-verbose for an agent-facing description, with phrases like 'which is the honest answer and not an error' adding nuance but not essential structure.

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?

Despite no output schema and no annotations, the description is remarkably complete. It explains what the returned document contains, how conflicts are resolved, what happens in edge cases, error conditions (409), auth requirements, and side effects. This is a fully specified behavior description for a complex 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?

The schema covers the single parameter projectId with a description ('Owned brand project id from list_brand_projects'), and schema coverage is 100%. The description adds owner-scoping context, but this is already implied by 'Owned' in the schema and is more of an access requirement than a parameter semantic. Thus, the baseline 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's purpose: returning the brand as one ready-to-build document, specifically the kit's DESIGN.md with pinned layers written in. It distinguishes itself from sibling tools by explicitly naming get_design_md, get_image_direction, get_interface_style, and get_page_recipe and explaining why using them separately is inferior.

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 explicit when-to-use guidance: 'Use this instead of assembling get_design_md plus get_image_direction plus get_interface_style plus get_page_recipe yourself.' It also covers edge cases—no pinned layers returns the kit's DESIGN.md, a locked layer is named with an upgrade path, and no chosen kit returns 409—so agents know when the tool is appropriate and what to expect.

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 takes full responsibility for behavioral disclosure. It transparently covers credit consumption per variation/scene combination, refunds on failed enqueues, the async queue behavior, the response containing job id and polling URL, and the permission requirement. This exceeds typical disclosure levels.

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 tightly written sentences front-load the core action, then efficiently cover cost, failure handling, response contents, and required permission. Every sentence adds value with zero wasted words.

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?

The description covers the essential aspects for a queueing tool: what it does, cost, failure refund, response content, and permission. It doesn't elaborate on polling mechanics, but the sibling get_mockup_job and the polling URL hint provide sufficient context. Given no output schema or annotations, this is reasonably complete.

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 schema already provides 100% parameter description coverage, so the baseline is 3. The description adds value by explaining the cost model tied to the variation/scene combinations and the async queue semantics, which enriches understanding of how the parameters relate to behavior.

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 a specific verb and resource: 'Queue photographic mockups for selected variations and template scenes.' This clearly distinguishes the tool from siblings like list_mockup_jobs and get_mockup_job, which list or retrieve mockup jobs.

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 for use: it queues mockups, explains the credit cost model, and notes the kits:write permission requirement. It doesn't explicitly name alternative tools or say when not to use it, but the context is strong enough to imply the primary use case.

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 full transparency burden. It goes beyond a simple mutation warning by detailing the credit cost model ('one per uniquely persisted name, charged only after the rows commit, so a failed run costs nothing'), the idempotency guarantee, and the provenance recording. This gives the agent critical operational knowledge not available in 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?

The description is a single dense paragraph with every sentence contributing essential information: purpose, persistence, costs, idempotency, alternative, and scope. There is no repetition of schema content and no fluff. It is front-loaded with the tool's core action and then logically covers side effects and usage nuances.

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 7 parameters, nested objects, and no output schema, the description covers most critical context: cost behavior, idempotency, persistence, provenance, and alternative tools. The only minor gap is that it does not describe the return value or response shape, which would normally be needed with no output schema, but the mention of 'returns the original result' partially implies the behavior. Overall, it is very complete.

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 baseline of 3 applies. The description adds contextual guidance around `idempotencyKey` ('Always pass a stable idempotencyKey so a retry after a timeout cannot bill twice') and reinforces that `count` corresponds to persisted-name credits, but most parameter-level semantics are already in the schema. It does not meaningfully compensate beyond that.

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 a specific verb+resource+outcome: 'Generate brand names... and persist them to the project board's generated column with full model, prompt-version, and credit provenance.' It also distinguishes itself from the sibling `add_name_candidates` by noting the alternative tool is for externally produced names, so there is no ambiguity about its role.

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?

Explicit usage guidance is provided: 'Use it when you want Identity Forge to author the names; if your own agent or an offline process produced them, use add_name_candidates instead, which is free.' This names the exact alternative tool and gives a clear decision criterion. It also notes the required `naming:write` scope, which helps the agent determine 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?

No annotations are provided, so the description carries the full burden. It discloses read-only side effects ('it mints no version and never moves a pin'), field semantics (revision vs chosenRevision, drift, resolved:false, locked:true), the meaning of meta.drifted, and the required kits:read scope. This is exceptionally transparent for a read operation.

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?

Although longer than average, every sentence contributes distinct, high-value information: purpose, usage timing, field behavior, edge cases, preview link, safety guarantees, and authentication requirements. It is front-loaded with a clear definition and wastes no words.

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 no output schema and no annotations, the description thoroughly explains the return values (revision, chosenRevision, drift, meta.drifted, resolved, locked, links.preview), edge cases, side effects, and auth. It also references the sibling add_brand_layer for mutation, making it complete for an agent to invoke 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?

The only parameter, projectId, is fully described in the schema as 'Owned brand project id from list_brand_projects.' The description adds no further parameter-specific detail, but with 100% schema coverage this is acceptable. The baseline of 3 applies because the schema already does the heavy lifting.

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 a specific definition: 'What a brand project is composed of on top of its design kit: its image direction, its interface style, and its page recipes.' The verb 'Read' is clear and the resource is unambiguous. It also distinguishes itself from mutating siblings like add_brand_layer and remove_brand_layer by framing itself as the read-before-change tool.

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 instructs 'Read this BEFORE changing any of them' and explains it is the only place to see what the user chose and whether drift exists. It also tells the agent when to stop ('a brand with nothing to report answers 0 and you can stop') and points to add_brand_layer as the decision point for accepting a drifted revision. This is strong when-to-use guidance with 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?

No annotations are provided, so the description carries the full burden. It discloses that the operation is read-only, requires the kits:read scope, and returns 404 identically for nonexistent and non-owned projects, preventing existence probing. It also details the exact data returned, including share state 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?

The description is concise despite its length; each sentence serves a purpose. It front-loads the core purpose, then contrasts with a sibling, lists use cases, explains security behavior, and ends with scope/read-only note. No redundant phrases.

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 no output schema, the description sufficiently explains return contents and behavior. It also covers prerequisites (kits:read scope), ownership constraints, and use cases, making it fully self-contained for an agent to select and invoke the tool 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 covers 100% with a description 'Owned brand project id from list_brand_projects.' The tool description reinforces the ownership restriction but does not add new parameter-specific details beyond the schema. The baseline for full schema coverage is 3, and no extra syntactic or format guidance is provided.

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 reads one board in full, enumerating contents (variations, kits, brand name, domain, label, notes, share state, URLs). It explicitly distinguishes itself from list_brand_projects, which gives summaries and counts.

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 provides specific use cases: checking own work after attaching variations, answering 'what did we send them', and reading share state before changing it. It also explicitly names the alternative (list_brand_projects) and notes the tool returns 404 for non-owned projects, clarifying when not to use it for discovery.

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 transparency burden and does well: it discloses owner-scoping, the required 'kits:read' permission, and a security property (never hands back a Pro kit's tokens by another door). It doesn't cover output shape or errors, but for a read tool this is substantive.

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 fairly compact (four sentences), but the opening sentence is awkwardly phrased and the 'Needs kits:read' note feels appended. All sentences contribute information, yet the structure could be smoother.

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 read operation with two well-documented parameters and no output schema, the description covers purpose, scope, security, and permission. It lacks explicit return-format detail, but that is not critical here given the tool's simplicity and the schema's richness.

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 each parameter's description already provides source references (e.g., 'from list_brand_projects'), so the description adds no extra parameter-level meaning. Baseline 3 is appropriate as the schema does the heavy lifting.

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 title states 'Read one stored brand project version' and the description says 'The full snapshot a given version of a brand project recorded,' making the resource and action clear. It distinguishes from siblings by emphasizing 'full snapshot' and the kit-referencing behavior, though the first sentence is grammatically awkward.

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 ownership context ('Owner-scoped') and implies usage for fetching a specific version's snapshot, but it lacks explicit guidance on when to use this tool versus list_brand_project_versions or diff_brand_project_versions. No alternatives 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?

With no annotations, the description fully discloses behavior: read-only, writes nothing to disk, returns the text. It also explains the 403 response for entitled Pro kits without leaking the brief, covering error and security behavior comprehensively.

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 dense but every sentence earns its place: content overview, usage context, read-only guarantee, and auth behavior. It is logically structured and free of redundancy.

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 one-parameter fetch tool, this description covers the document's contents, when to use it, side effects (none), and auth/error behavior. No critical context is missing, even in the absence of an 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?

The schema provides 100% coverage for the single parameter, including detailed guidance on slug vs id. The tool description adds no additional parameter semantics, and its 'by slug' phrasing is slightly narrower than the schema's id-or-slug, but this does not reduce the baseline score.

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 it fetches the complete DESIGN.md brief for a design kit by slug, enumerating the document's contents. It distinguishes itself from sibling writer tools like apply_theme and other get_* tools by positioning DESIGN.md as the design source document.

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 states when to use the tool: 'Read it before implementing a kit, or when the user wants to review a direction before committing to it.' It also names apply_theme as the alternative that writes, providing a clear when-not-to-use signal.

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 transparently discloses read-only behavior ('writes nothing to disk'), access control ('Free records are public; a Pro record returns 403'), and error handling without leaking payload. This exceeds the typical level of behavioral detail.

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 compact and front-loaded: it opens with the core action, then usage context, then safety/auth details. Each sentence adds distinct information, with no redundant 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?

For a simple two-parameter tool with no output schema, the description covers what the tool does, how to use it, its output formats, and its safety/auth profile. It gives an agent enough to invoke it correctly without further research.

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 schema already provides full parameter descriptions (100% coverage), so the description need not repeat them. It adds semantic value by mapping output formats to use cases: 'Markdown for reading and briefing or JSON for programmatic use,' which helps agents select the right format.

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 retrieves one image direction's full implementation export, with a specific verb ('Retrieve') and resource. It distinguishes from listing siblings by specifying 'one' and the export format options.

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 explicit usage context: 'This is what you follow when generating, sourcing, or art-directing imagery for the project.' It also clarifies it pairs with the design kit rather than replacing it, but does not explicitly name alternative tools or exclusions, so it stops short of full when/when-not guidance.

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 of behavioral disclosure. It explicitly states 'Read-only: it returns the text and writes nothing to disk' and details the 403 upgrade-path behavior for Pro records without leaking the payload. This is unusually transparent and safety-relevant.

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 dense sentences, each earning their place: the action and formats, the conceptual caveat about needing a design kit, and the auth/403 behavior. The core purpose is front-loaded with no redundant 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?

For a simple two-parameter retrieval tool with no output schema, the description covers purpose, formats, the content caveat, read-only safety, and error behavior. It does not specify the exact JSON/Markdown structure, but the schema and format enum make this adequate.

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 context that the export contains only render-grammar rules and that Markdown is for reading while JSON is for programmatic use, but it does not materially extend the already-detailed schema descriptions of 'slug' or 'format'.

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 a specific verb ('Retrieve') and resource ('one interface style's full implementation export'), names the two formats (Markdown/JSON), and clarifies that the export contains only render-grammar rules. This clearly distinguishes it from listing tools and design-kit tools.

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 context: use this for the implementation export, combine it with a design kit's tokens/typography/motifs/brand rules, and notes the read-only, entitlement behavior. It does not explicitly name alternative sibling tools like get_design_md or get_tokens, so it stops short of a full 5.

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 full burden of behavioral disclosure. It reveals the response is a large whole design kit, requires kits:read permission, and that a 404 is ambiguous (event not yours vs. kit not owned). These are non-obvious behavioral traits that help the agent anticipate outcomes and avoid misdiagnosis.

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 a single paragraph with multiple clauses, but every sentence earns its place. It is front-loaded with the core purpose, then provides use cases, usage prerequisites, and error semantics. Slightly verbose with phrases like 'rather than decorative,' but overall appropriately sized for the complexity.

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 tool has only two parameters, no output schema, and no annotations, the description is exceptionally complete. It covers purpose, usage flow, auth requirements, result size, and ambiguous error behavior. The agent knows exactly what to expect and how to invoke the tool 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?

The input schema already has 100% coverage for slug and eventId, providing baseline 3. The description adds meaning beyond the schema: eventId comes specifically from list_kit_history (not a version number, as also reiterated), and both parameters must satisfy ownership conditions. It also clarifies the 404 ambiguity tied to these parameters, adding semantic depth.

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 explicitly states the tool reads a kit as it stood at a specific history entry, using a ledger metaphor. It distinguishes itself from siblings like list_kit_history (which lists entries) and update_theme (which changes state) by emphasizing the point-in-time snapshot purpose and use cases like diffing and restoring.

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 gives clear when-to-use guidance: call list_kit_history first, then fetch only the desired entry. It also explains what not to assume (event id alone is insufficient) and provides an alternative use case (PATCH payload through update_theme to restore). This is explicit and practical.

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 fully carries the burden of behavioral disclosure. It reveals that the response is large, that version numbers are immutable, that the tool returns the entire payload, and that it is gated like an export (403 for unentitled Pro kits). It also states the required scope ('Needs kits:read'). This is rich, non-obvious 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 four sentences, each conveying essential information without redundancy. It front-loads the core purpose, then provides usage guidance and critical behavioral notes in a logical flow. No wasted words.

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?

Despite no output schema, the description is complete enough: it explains response size, permissions, gating behavior, and the distinction from diff_kit_versions. Users can accurately predict what the tool will do and what constraints apply.

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%, with both slug and version having detailed descriptions. The tool description adds a small note about version permanence, but the schema already explains version 0 and positive integers. Since the schema does the heavy lifting, a 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 identifies the tool as retrieving the full snapshot of a specific stored kit version, using specific language like 'full snapshot' and 'as it was at that moment.' It explicitly distinguishes itself from diff_kit_versions, which addresses a different need, so it is well-differentiated from siblings.

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 exactly when to use this tool ('when you need the old values themselves') and when to prefer an alternative ('diff_kit_versions is the cheaper answer when you only need to know what moved'). It also provides context about size and gating, which helps decide when to invoke it.

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 full burden of behavioral disclosure. It explicitly states 'Read-only' and 'Requires kits:read', which conveys the safety profile and auth requirement. It also enumerates return fields (status, completed count, errors, result URLs), giving agents a clear picture of what to expect. It lacks details on error behavior or rate limits, but for a simple read operation 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 two sentences, front-loaded with the action and return fields, followed by a terse note on read-only and permission. Every word earns its place; no redundancy or 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?

For a simple single-resource read tool, the description covers the essentials: what it does, what it returns, and its permissions. With no output schema, the description's mention of status, count, errors, and URLs compensates well. It could add context about typical usage after generate_mockups, but the parameter schema already provides that linkage, so the overall completion is strong.

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 have rich descriptions in the schema (jobId from generate_mockups or list_mockup_jobs; projectId from list_brand_projects). The tool description itself adds no parameter-specific meaning, so the baseline of 3 applies as the schema does the heavy lifting.

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 uses a specific verb ('Poll') and resource ('one mockup job in its project'), clearly stating what it returns (status, completed count, errors, result URLs). This distinguishes it from siblings like list_mockup_jobs (lists many) and generate_mockups (creates jobs).

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 on when to use this tool: to poll a single mockup job for status and results. It does not explicitly name alternatives or exclusions, but the 'Poll one mockup job' phrasing implies usage after job creation, and the read-only nature is stated. Missing an explicit contrast with list_mockup_jobs, but context is sufficient.

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 full transparency burden. It clearly states side-effect and access characteristics: 'Read-only and free' and 'Requires the naming:read scope.' It also discloses behavioral boundaries, such as not ranking or scoring candidates, and describes the extent of returned data (up to 100 candidates with evidence). This exceeds what is typical and gives the agent a clear behavioral model.

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 four sentences long but every sentence earns its place: the first enumerates the payload, the second gives timing guidance, the third sets expectations about non-behaviors, and the fourth covers access and safety. It is well-structured, front-loaded, and free of 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?

For a one-parameter, read-only context tool with no output schema, this description is remarkably complete. It covers what is returned, when to call it, what it avoids, access requirements, and linkage to existing board data. An agent has enough information to invoke it appropriately and anticipate its behavior without surprises.

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 schema covers 100% of the single parameter with a clear description ('Owned naming project id from list_naming_projects') and a UUID format. The tool description adds useful context about what the parameter is used for (loading project brief, candidates, etc.), but it does not add new parameter-level semantics beyond the schema. Thus the schema-coverage baseline 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 opens with a specific, action-oriented summary: 'Load everything you need to plan naming research in one call,' then enumerates concrete deliverables (project brief, candidates with evidence, available checks, workflow guidance, template). It clearly distinguishes itself from siblings like list_naming_projects and generate_names by focusing on consolidating research context rather than creating or listing entities.

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 tells the agent when to call it: 'Call it before orchestrating substantial research so you do not re-run checks that already exist on the board.' It also clarifies what the tool intentionally does not do (rank, score, or choose delegation model), preventing misuse. This is strong, actionable guidance for selecting this tool over 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 provided, the description carries the full burden and does so admirably. It explicitly states 'Read-only: it returns the text and writes nothing to disk,' and discloses access-control behavior: free records are public, while Pro records return 403 with an upgrade path without leaking the payload.

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, front-loaded with the primary action, and every sentence earns its place by adding either purpose, usage context, or critical behavioral/access details. There is no fluff.

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?

The tool has only 2 parameters, no output schema, and no annotations, so the description carries more weight. It explains the return type (full implementation export), format options, and access behavior. It could go further by describing the structure of the exported payload, but for a simple read-only tool the description is quite complete.

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 some value by associating markdown with 'reading' and JSON with 'programmatic use,' but this largely restates the format enum and does not meaningfully enhance understanding beyond the schema's already detailed slug and format 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 uses a specific verb and resource: 'Retrieve one page recipe's full implementation export.' It distinguishes itself by targeting a single page recipe (contrasting with list_page_recipes) and clarifies its relationship with a design kit, which supplies visual and interaction rules.

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: this tool is used to obtain the full implementation of a single page recipe, paired with a design kit. It implies when to use it (when you need the page's structure and argument) but does not explicitly name alternative tools or state when not to use it.

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 full burden of behavioral disclosure. It reveals important behaviors: a project without context returns null, a non-existent project returns 404, and the call is free and requires kits:read permission. This goes well beyond the schema and gives the agent crucial expectations for handling responses.

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 yet dense with useful information. Each sentence serves a distinct purpose: the first defines the content, the second gives usage timing, the third clarifies edge-case behavior, and the fourth states permissions and cost. No fluff or redundancy.

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?

Despite having no output schema and no annotations, the description is remarkably complete for a read tool. It explains what the context contains, when to use it, what null vs. 404 mean, and the required permission. This is sufficient for an agent to invoke the tool correctly and interpret the response appropriately.

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 projectId is already described as 'Owned brand project id from list_brand_projects.' The tool description does not add additional parameter-level meaning beyond what the schema provides, so the baseline of 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 clearly states the tool reads a project's stored context and enumerates what that context contains (what it does, who it's for, design constraints, ruled-out options, screens, and foundation). It is specific with a verb and resource, and it distinguishes itself from the sibling set_project_context by explicitly saying to read before that call.

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 gives explicit usage guidance: read before proposing anything for an existing project and before calling set_project_context, because set_project_context replaces rather than merges. It also clarifies the null vs. 404 distinction, which tells the agent when a project exists without context versus when the project itself doesn't exist.

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 fully discloses behavior: 'Read-only: it returns the file contents as text and writes nothing to disk.' It also reveals the 403 error for entitled Pro kits, adding auth expectations beyond schema/annotations.

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, usage guidance, and behavioral transparency. It is front-loaded and free of 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?

For a read-only retrieval tool with 2 parameters and no output schema, the description covers all essential aspects: what it does, content scope, when to use, alternatives, side effects, and auth. It is sufficiently complete for an agent to select and 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%, including detailed descriptions for both 'slug' and 'format' with enum values. The description adds only marginal context like 'format that matches the target stack,' but the schema already explains parameter semantics, so the baseline 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 design kit's machine-readable tokens in a format matching the target stack, specifying the content coverage (28 semantic color roles, typography, spacing). It distinguishes itself from siblings by explicitly contrasting with get_design_md and apply_theme.

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 explicit guidance: 'Use it to wire a kit into an existing styling layer when you do not need the written brief; pair it with get_design_md when you also need the rules.' It also names apply_theme as the alternative for writing tokens into a project, covering when-not-to-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 are provided, so the description carries the full burden, and it thoroughly discloses the read-only nature, no arguments, no pagination, no side effects, and required kits:read scope. This leaves no ambiguity about behavioral traits.

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, front-loaded with the main purpose, and every sentence adds distinct value: purpose, usage context, and behavioral/scope details. No wasted words.

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 no annotations and no output schema, the description covers return fields, pagination behavior, side effects, arguments, and scope. For a zero-parameter list tool, this is fully complete and leaves no 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?

The schema has zero parameters, and the description explicitly confirms 'takes no arguments', adding clarity beyond the empty schema. This preempts any confusion about hidden or required parameters.

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 uses a specific verb ('list') and resource ('brand projects'), and explicitly enumerates the returned fields (name, brief, variation count, client share link existence). It clearly distinguishes from sibling tools by focusing on brand projects and referencing related tools like add_brand_variation and share_brand_project.

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 explicitly states when to use this tool: before add_brand_variation or share_brand_project to find a projectId, and to check whether a board already exists to avoid duplicates. This provides clear context and 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 transparency burden and excels: it discloses 404 behavior for non-owned projects, the absence of a tier gate, the deliberate exclusion of sharing info, and the meaning of an empty timeline. It also notes permission requirements.

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 longer than minimal but each sentence adds unique value: purpose, scoping, content coverage, sharing rationale, empty-timeline meaning, and permissions. It's front-loaded with the primary purpose and remains readable.

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?

Despite having no output schema, the description thoroughly explains what the timeline records (name, domain, fonts, layers, context, variations, reorder), the ordering, edge-case behavior, and permissions. This is complete for a list 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?

The input schema covers 100% of parameters, so the baseline is 3. The description adds some context around projectId (ownership scoping) but doesn't elaborate on limit or before, which are already documented in the 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 clearly states the tool lists a brand project's version history, newest first, with details on what changed, when, and by whom. It distinguishes itself from siblings like get_brand_project_version (single version) and diff_brand_project_versions (comparison) by focusing on the full timeline.

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 gives clear usage context: owner-scoped, no tier gate, free to call, requires kits:read, and explains that non-owned projects return 404. However, it doesn't explicitly name alternative tools or say when not to use it, so only a point off.

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 full behavioral disclosure. It explicitly states 'Read-only, changes nothing,' reveals edge cases ('Anonymous commenters appear as 'Guest'...' and 'deleted comments are omitted'), and specifies scope requirements ('Requires the kits:read scope'). This is unusually transparent for a tool description.

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 the core purpose, then expands with context, usage guidance, edge cases, and requirements. Every sentence earns its place—background context, actionable follow-ups, edge cases, and scope are all relevant. Despite length, it is dense and efficient, not redundant.

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 no output schema, the description adequately describes the returned content: variation, author display name, ordering, and omission of deleted comments. It also covers invocation context, read-only nature, no pagination, and required scope. This is complete for a single-parameter, non-nested list operation.

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 has 100% coverage with a good description of projectId ('Owned brand project id from list_brand_projects'), so the baseline is 3. The tool description does not add meaningful parameter semantics beyond what the schema provides; it only contextualizes the operation around the share link, not the parameter itself.

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 uses a specific verb ('Read') and identifies the exact resource: 'what the client wrote on a project's variations through the share link.' It clearly distinguishes this from sibling tools by detailing scope ('a project's variations'), ordering ('oldest first'), and included fields (variation, author display name), making the tool's purpose unambiguous.

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 explicit usage context: it is 'the return leg of the share loop' and tells the agent to 'Call it before revising.' It names concrete follow-up tools ('update_brand_variation, update_theme, or remove_brand_variation'), and states a limitation ('takes no pagination'). This is strong when-to-use guidance with clear 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 and does so excellently: 'Returns judgment summaries with no export payload', 'Read-only and free', and 'Pro records appear in the list without exposing their contents.' These are key behavioral disclosures 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 composed of five focused sentences, each adding distinct value: purpose, when to use, return behavior, relationship to design kit, and access limitations. There is no redundancy or fluff.

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 read-only list tool with 5 optional parameters and no output schema, the description sufficiently covers the purpose, usage context, return behavior (summaries), pointer to the detailed sibling tool, and read-only/free status. It is a complete description for an agent to decide when and how to invoke it.

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%—every parameter has a clear description in the schema. The tool description does not add additional parameter semantics beyond the schema, so the baseline 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's purpose: 'Browse image directions' and explains what image directions are (process, treatment, subject matter for photography/illustration). It also distinguishes itself from the sibling get_image_direction by specifying that it returns judgment summaries rather than the implementable version.

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 gives explicit usage context: 'Use one when a kit is chosen but the imagery still has no direction...' and directs to the alternative tool: 'pick a slug and call get_image_direction for the implementable version.' This clearly states when to use this tool vs. the sibling.

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 full burden of behavioral disclosure. It clearly states that the tool is read-only and free, that it returns judgment summaries with no export payload, and that Pro records appear without exposing their contents. This gives the agent a precise picture of side effects and access characteristics.

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 'Browse interface styles' and each sentence earns its place: definition, differentiation, usage context, return behavior, and note on Free/Pro. It is detailed without being redundant, and no sentence 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 list tool with 5 filter parameters and no output schema, the description is highly complete. It explains the return format (judgment summaries, no export payload), guides the next step (call get_interface_style), and covers the Free/Pro access model. The schema handles parameter syntax, so the description fills in all contextual 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 100%, so the baseline is 3. The description adds value beyond the schema by explaining that Pro records appear in the list without exposing their contents, clarifying the tier parameter's behavior. It also frames the return as judgment summaries, which helps the agent understand what filters will yield.

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 a specific verb+resource ('Browse interface styles') and clearly defines what a style is: a neutral render grammar that decides how surfaces and hierarchy render. It also distinguishes styles from themes/palettes/brand rules and from the companion get_interface_style tool, making the tool's purpose unmistakable.

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 gives an explicit when-to-use scenario ('Use one when the kit is settled but the layout still defaults to generic cards on a grid') and an explicit alternative ('pick a slug and call get_interface_style for the implementable version'). It also clarifies what the tool is not for ('not a second source of palettes, fonts, or brand rules'), providing clear when-not guidance.

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 full burden. It discloses 404 for unowned kits, opaque cursor rejection, metadata-only results, and the required kits:read permission. It also clarifies ordering and that apply-to-brand events appear here and nowhere else, going well beyond a simple 'list' label.

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?

Dense but each sentence adds unique value: event scope, sibling comparison, event id depth, token absence, ownership 404, cursor rules, and permission. There is no filler, and the structure is logical.

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?

Covers return semantics (rows, event ids, meta.nextCursor), edge cases (404 for catalog kits, opaque cursor rejection), and authentication (kits:read). With no output schema, this is sufficient for an agent to invoke the tool 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?

All three parameters are fully described in the schema (100% coverage), so the baseline is 3. The description reinforces cursor opacity and slug ownership but does not add new parameter-level syntax beyond what the schema already 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?

Clearly states it lists a kit's history ledger with specific event types (creation, save, applied to brand). It explicitly contrasts with list_kit_versions and names the distinguishing use case, so purpose is unambiguous and differentiated from siblings.

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?

Provides explicit when-to-use guidance: 'this is the tool that answers whether a kit was ever actually used rather than merely edited.' Also explains the ownership condition (API-key kits vs curated catalog) and 404 behavior, giving clear context for when to call and what to expect.

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 full responsibility for behavioral disclosure. It covers token cost ('Metadata only, so no tokens come back'), pagination ('Paginated newest-first through meta.nextBefore'), edge cases for catalog kits (empty timeline, currentVersion 0), the difference between '0' and missing value, and permission requirements ('needs kits:read'). It also discloses Pro kit label null 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 long but every sentence contributes essential context—purpose, usage guidance, exclusions, alternatives, edge cases, and permissions. It is front-loaded with the core purpose. However, it is a single dense paragraph without line breaks, which slightly harms readability, though not enough to lower below 4.

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?

The description fully covers the tool's behavior for a read operation: what it returns, how pagination works, edge cases for catalog and Pro kits, and permission requirements. It also clarifies the meaning of the 0 currentVersion state. No output schema exists, but the description sufficiently explains the expected content without needing to detail the exact response structure.

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 baseline is 3. The description adds minimal extra parameter meaning beyond the schema—it mentions pagination via meta.nextBefore, but the schema already explains 'Pass meta.nextBefore from the previous page' for the before parameter. No new parameter semantics are introduced.

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 function: 'The kit's VERSION timeline, newest first: which version, when, by whom, and the author's note.' It distinguishes from siblings by explicitly contrasting with list_kit_history, get_kit_version, and diff_kit_versions, making the purpose unmistakable.

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?

Provides explicit when-to-use guidance: 'Use it to answer the question a repo built against this kit actually has, which is whether the kit has moved since.' It also states when not to use it ('It is not the full history...') and names the alternatives (list_kit_history, get_kit_version, diff_kit_versions).

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?

Since no annotations are provided, the description carries the behavioral burden. It discloses read-only nature, required permission scope, ordering, and included fields (status, progress, errors, result URLs). This goes beyond a minimal description, though it omits details like pagination.

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 immediately convey purpose, ordering, content, and permissions. No filler or redundant 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 simple list tool with one parameter and no output schema, the description covers the core behavior, expected fields, and access requirements. It may not mention pagination limits, but overall it's sufficiently complete for an agent to decide when to invoke.

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 only parameter projectId is fully documented in the schema with description 'Owned brand project id from list_brand_projects.' Since schema coverage is 100%, the description adds little beyond the tool's own mention of 'one brand project'.

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?

Description uses specific verb 'List' with resource 'mockup jobs' and scope 'one brand project's', also mentions ordering 'newest first' and content. This distinguishes it from sibling get_mockup_job which fetches a single job.

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?

States it lists one brand project's jobs, implying you need a projectId from list_brand_projects (defined in schema). Also says 'Read-only' and 'Requires kits:read', giving context on when it's safe to use. However, it does not explicitly name alternatives 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?

With no annotations, the description carries the burden and does well: it states 'Read-only, paginated, and free' and mentions the required 'naming:read' scope. It also discloses the return payload details (status, rank, notes, provenance, updatedAt) and the stale-write mechanism, providing behavior beyond simple read semantics.

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 dense but efficient—five sentences that stay on topic. It front-loads the core purpose, then adds return-value details, use cases, and constraints. Every sentence contributes information without padding.

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 4 parameters, no output schema, and no annotations, the description is remarkably complete. It covers the return fields (compensating for missing output schema), pagination behavior, filtering, scope requirement, and the relationship to sibling write tools, giving an agent all necessary context to invoke and interpret the result.

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 schema already documents all four parameters. The description adds contextual meaning by framing statuses as filtering by kanban column ('shortlisted or finalist') and relating pagination to a list view. This goes beyond the schema's basic descriptions, earning a 4.

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 starts with 'Read one project's candidate kanban,' which precisely identifies the resource and action. It distinguishes from sibling list tools by focusing on the candidate kanban and explicitly referencing related write tools (move_name_candidates, rank_name_candidates), making it clear this is the read-side counterpart.

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 gives practical context: 'Filter by status to review a single column' and notes that the returned updatedAt is passed to move/rank tools to guard against stale writes. This implies when to use the tool but does not explicitly state exclusions (e.g., 'use X instead when...'), so a 4 is appropriate.

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 fully carries the behavioral disclosure burden. It states read-only, paginated, free, requires the naming:read scope, and enumerates return fields including credit reservation/consumption. This is comprehensive for a read-only list 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?

Two well-structured sentences: the first lists what the tool returns, and the second provides use cases and key properties. Every sentence delivers useful information with no redundancy.

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?

Despite lacking an output schema, the description effectively documents return values by listing all major fields (fingerprint, recipes, model, credits, status, timestamps). It also covers pagination, permissions, and cost implications, making the tool's behavior fully understandable.

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 baseline is 3. The description adds context like 'for one project' and 'paginated' but doesn't explain the parameters themselves beyond what the schema already provides. No additional semantics are introduced.

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 reads the generation ledger for one project, listing every generate_names run with specific data fields. This specific verb+resource+scope distinguishes it from sibling list tools like list_naming_recipes and list_naming_projects.

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 gives two use cases: tracing where a set of names came from and checking if a failed run charged credits before retrying. While it doesn't name alternative tools directly, the context strongly implies when this tool is appropriate in relation to other listing tools.

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 fully carries the burden. It explicitly discloses that the operation is read-only, paginated, free, and requires the naming:read scope. This is a high level of transparency for a list tool, covering safety, authorization, and paging 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 concise—three sentences total—with the core purpose front-loaded. Every sentence adds value, and there is no redundant or filler content.

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?

Despite lacking annotations and output schema, the description covers purpose, usage context, return fields, security scope, and paging. For a simple list tool with two well-defined params, this is complete and actionable.

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 provides 100% coverage for the two parameters (limit and offset), including descriptions and ranges. The description only mentions 'paginated' which is a general behavior, not parameter-specific detail. Baseline 3 is appropriate given schema completeness.

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 lists persistent naming boards with specific fields (id, name, brief, researched TLDs, chosen name, candidate counts). It distinguishes itself from siblings like list_naming_recipes and create_naming_project by emphasizing ownership and the purpose of recovering projectId.

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?

Explicit guidance is provided: 'Start here to recover the projectId for an existing brief' and 'only call create_naming_project when nothing here fits'. This directly tells the agent when to use this tool versus the primary alternative, with a clear rationale.

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 of disclosing behavior. It states the tool is 'Read-only, free, and needs no arguments,' and describes the output contents. It also clarifies it lists only 'public' recipes, adding a limitation not implied by 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: the first sentence states purpose, the second gives usage guidance, the third adds a stability note, and the fourth summarizes traits. Every sentence adds value with no 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 simple no-arg list tool with no output schema, the description is thorough. It explains what the tool returns, when to use it, and its safety profile. No gaps remain for the 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?

The tool has zero parameters, so the schema already covers everything. The description adds an explicit 'needs no arguments' statement, which is helpful but redundant. Baseline 4 is appropriate for a no-argument tool.

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 lists 'every public naming strategy Identity Forge can generate from' and specifies the returned fields (id, intent, generation instruction, settings). It distinguishes itself from sibling list tools like list_page_recipes by focusing on naming recipes.

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 instructs to 'call it before generate_names' to select recipe ids, and notes 'you can skip this once you already know the ones you want.' This gives clear when-to-use and when-not-to-use guidance, referencing the specific sibling tool it supports.

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 full behavioral transparency. It discloses return format ('judgment summaries'), the absence of an export payload, the distinction between legacy-sequence and communication-idea records, and the scope boundary ('covers structure and argument, not visuals'). It also explicitly notes 'Read-only and free,' which is essential behavioral context.

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 dense but every sentence earns its place: purpose, usage trigger, alternative, return behavior, model field nuance, and scope limitation. It is front-loaded with the main verb and resource, and flows logically without fluff.

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?

The tool is simple (list/read) but the domain has nuance. The description covers return format, the model field meaning, and what the tool does not cover (visuals). With no output schema, this level of description is ample for an agent to understand what to expect and how to proceed.

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 has 100% coverage for all four parameters, so the baseline is 3. The description does not add parameter-specific detail beyond what the schema provides; it focuses on the returned records' model field. That is fine but not additive to parameter understanding.

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 a specific verb ('Browse') and a clear resource ('page recipes'), then explains what page recipes are and what they do. It also distinguishes this tool from its sibling get_page_recipe by framing list_page_recipes as the browsing step and get_page_recipe as the follow-up. This makes the purpose unmistakable.

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 explicitly states when to use this tool: 'Use one when you know what a page must achieve but not how to sequence it.' It also names the alternative: 'call get_page_recipe for the implementable version.' It adds a caution to read the model field before following a record, which is actionable guidance.

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 transparency burden. It discloses pagination behavior (total + next offset), that `use` re-orders rather than narrows, that summaries lack tokens/DESIGN.md/fonts, that fitness scores are computed with `reason` absent for all kits, and that the tool is read-only/free and lists Pro kits without exposing contents.

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 long but information-dense; every sentence contributes critical context such as catalog contents, filtering semantics, pagination, content absence, and alternatives. It is front-loaded with purpose and free of filler, though slightly verbose for a simple reader.

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?

No output schema exists, so the description explains the response shape (compact summaries with fields, total + next offset) and explicitly lists what is absent. It covers filtering, pagination, content limitations, and alternative tools, making it complete for a tool with this complexity.

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%, but the description adds non-obvious behavioral semantics beyond parameter descriptions: `use` re-orders instead of narrowing, `q` is synonym-aware, pagination requires paging through offsets, and the fitness score caveat (read the order, not the number). It also explains how to interpret `charts` blocks for data lanes, which is actionable and beyond 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?

Description opens with the specific verb and resource: 'Browse the published catalog as compact summaries,' and positions this as 'the main entry point for finding a design kit.' It also differentiates from siblings by directing token/DESIGN.md retrieval to get_design_md/get_tokens and naming search_themes as the alternative for subtle briefs.

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 states when to use: 'This is the main entry point for finding a design kit' and provides exclusions: 'Prefer search_themes when the brief is too subtle to rank against a lane.' It also advises using get_design_md or get_tokens for full contents, giving concrete 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 provided, the description takes on full responsibility. It discloses the tool is 'Read-only and free,' states a core behavioral limitation 'ranks on color alone and ignores mood, audience, and use case,' and warns the output is a shortlist needing further validation. This is highly 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 appropriately compact—three sentences that front-load the core purpose, then provide usage guidance, limitations, and alternatives. Every clause adds value; no wasted words or redundancy.

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 only two parameters and no output schema, the description covers all critical aspects: purpose, relevance, limitations, complementary actions, and safety. It gives enough context for an agent to know when and how to invoke it, and what to do with the 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?

The input schema already provides 100% description coverage for both parameters, so the baseline is 3. The description reinforces the meaning of 'colors' (brand colors the user owns) but adds no new syntax or formatting details beyond the schema, which is sufficient.

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 a specific verb 'Rank' and clearly identifies the resource 'published kits' and the scope 'by how close their palette sits to colors the user already owns, using perceptual color distance rather than string matching.' This precisely distinguishes it from siblings like list_themes or search_themes, which do not rank by color fit.

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 states when to use: 'when a brand has existing colors that the design system has to live with.' It also gives a clear exclusion: 'When the user has no fixed colors, list_themes or search_themes will serve them better.' Additionally, it advises to 'check the rest of the fit with get_design_md before committing,' naming the complementary tool.

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 exist, so the description carries full burden, and it delivers: it discloses atomicity ('one atomic write'), the hard constraint that a project holds exactly one selected candidate, the side-effect of setting the project's chosen brand name upon selection, and optimistic concurrency behavior via expectedUpdatedAt. The auth requirement is also stated. This is rich, non-redundant behavioral disclosure.

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 pack a dense but clear payload: purpose, alternatives, side effects, concurrency, and auth. No filler or redundancy; front-loaded with the core action.

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 mutation tool with nested operations, no annotations, and no output schema, the description covers all key operational facets: what is moved, column order, atomicity, uniqueness constraint, brand-name side effect, concurrent-write protection, and scope requirement. The only minor omission is return value, but that's not essential given the tool's action-oriented nature.

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, and the description adds little over the schema. The description mentions passing expectedUpdatedAt from list_name_candidates, but that information already exists in the schema property description. The 'up to 100 candidates' limit mirrors schema maxItems. Thus the description provides minimal additional parameter meaning.

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 a specific verb and resource: 'Progress up to 100 candidates through the kanban in one atomic write, and optionally replace their notes and evidence at the same time.' It explicitly contrasts with rank_name_candidates ('only reorders and leaves status alone'), making the tool's distinct purpose unambiguous. Columns are enumerated, removing any ambiguity about valid states.

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 explicitly recommends this tool for 'recording a decision and why you made it' and names the alternative (rank_name_candidates) that should be used for pure reordering. It also instructs the agent to pass expectedUpdatedAt from list_name_candidates to handle concurrent modifications, and states the required auth scope (naming:write). This is exemplary when-to-use guidance.

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 fully discloses behavioral traits: atomicity ('every ranking applies or none does'), scoped side effects ('changes ONLY the rank field'), required permission ('naming:write scope'), and cost ('spends no AI credits'). This completely carries the transparency burden.

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 sentences, each earning its place: purpose and constraints, rank semantics, side effects/alternative, and usage/requirements. The text is front-loaded with the core action and contains no redundancy.

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?

Despite the absence of annotations and output schema, the description covers atomicity, side-effect scope, permission, cost, and when-to-use versus alternatives. Together with the rich input schema, this forms a complete behavioral contract for 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% and already provides detailed parameter descriptions (rank semantics, candidateId source, expectedUpdatedAt's optimistic concurrency). The description adds no parameter-specific meaning beyond what the schema provides, 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 uses a specific verb ('Assign explicit user-facing priority ranks'), names the resource ('up to 100 candidates on one naming board'), and scopes the action clearly. It also distinguishes from the sibling 'move_name_candidates' by explicitly stating this changes only the rank field.

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 explicitly states when to use this tool ('express a deliberate shortlist order') and when not to ('not to record research'). It also directs to the alternative tool: 'use move_name_candidates when you want to progress a candidate or record a decision.'

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 full burden. It discloses that the tool requires an API key, costs 3 quota units, returns meta.depth and meta.order to clarify mode and ordering, returns 400 if context is missing, and explicitly says 'Creates nothing' to signal no side effects. This far exceeds the transparency normally expected.

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 a single paragraph but each sentence adds distinct value: purpose, candidate contents, ranking mode, differences from other routes, and prerequisite. It is front-loaded with the core function and avoids fluff, though it is somewhat dense in presentation.

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?

Even without an output schema, the description explains what the response contains (candidate self-cases, meta.depth, meta.order), the auth and quota conditions, the error scenario, and the read-only nature. For a tool with two parameters and no output schema, this fully equips the agent to select and 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 baseline is 3. The description adds contextual meaning to projectId by tying it to set_project_context and stored context, and clarifies that limit only controls candidate count. While limit is self-explanatory, projectId's prerequisite is well articulated, adding value beyond the 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 clearly states the tool recommends kit candidates for a specific product, grounded in stored project context. It distinguishes from siblings by emphasizing that it uses stored context instead of a re-sent description, and explicitly differentiates from list_themes and search_themes by cost and auth requirements, plus 'Creates nothing' clarifies side-effect-free behavior.

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 'Call set_project_context first' as a prerequisite and notes that a project without stored context returns 400. It also highlights the two differences from other discovery routes: higher quota cost and API key requirement, and explains the two modes (free candidates vs. ranked with Pro+key), which gives clear when-to-use and alternative comparisons.

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 full burden of behavioral disclosure. It clearly states the original is never modified, the copy is private until published from the web Studio, requires kits:write scope, and a Pro-tier source needs an entitled key. It also implies each call creates a new copy. The only minor gap is not describing the return value or error behavior, but the core side effects and prerequisites are well disclosed.

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 five sentences, each adding distinct value: core action, source types, use case, non-destructive guarantee, alternative tool, entitlement, privacy, and scope. It is front-loaded with the main purpose and contains no filler or redundancy.

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 tool's complexity (nested overrides, 3 params, no output schema), the description covers essential context: source eligibility, repeated-call strategy, alternative tool, permissions, entitlement, privacy, and non-destructive behavior. The schema already documents parameter structure, so the description need not repeat it. It is sufficiently complete for an agent to decide when and how to invoke it.

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 baseline is 3. The description does not add much beyond the schema: it mentions overrides are applied and that name defaults to a variation suffix, but those are already present in the schema. The repeated-call pattern is useful context but doesn't enrich parameter meaning beyond what 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 opens with a specific verb+resource: "Copy an existing kit into a new private kit with overrides applied." It clearly distinguishes itself from create_theme by explicitly naming that tool as the alternative for authoring rather than varying, and the scope (source types, private copy) is unambiguous.

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 gives explicit when-to-use guidance: "fast path when you want three or four variations on one direction: call it repeatedly against the same source with different overrides." It also provides an explicit exclusion: "Reach for create_theme instead when you are authoring a kit rather than varying one." Additional context about Pro-tier entitlement and private-until-publish further clarifies when this tool is appropriate.

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 full burden and does so thoroughly: confirms permanence, requires confirm:true, states idempotency (changed:false, no version), immediate effect, and required kits:write scope. No contradictions.

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 the core action, and each subsequent sentence adds operational detail (idempotency, swap guidance, effect timing). Nothing 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 destructive mutation with no output schema, this covers prerequisites, side effects, alternatives, and error behavior comprehensively. The absence of output schema is mitigated by transparent no-op handling.

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?

Despite 100% schema coverage, the description adds critical meaning: recordId should come from get_brand_layers not memory, confirm must be exactly true, and explains semantics of 'not composed' responses. This exceeds baseline.

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 a specific verb-resource pairing: 'Remove one composed record from a brand project.' It clearly scopes the operation to a single layer reference and distinguishes from sibling add_brand_layer by stating what is NOT removed (design kit and other axes).

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 contrasts with add_brand_layer: 'When the intent is to swap rather than to clear, call add_brand_layer with replace: true instead.' Also instructs to pass the id read from get_brand_layers, preventing stale-data misuse.

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 fully discloses behavioral traits: permanent deletion, no archive, comments lost, gap in sequence, confirm requirement, and auth scope. This far exceeds the minimum needed for safe use.

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 yet information-dense, with a clear opening and each sentence serving a distinct purpose (consequences, required confirm, ordering side effect, alternative). No fluff or repetition.

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 tool's complexity (permanent delete, side effects, alternatives), the description is complete: it covers effects on client view, comments, sequence gaps, required confirm, auth scope, and related tools. No output schema or annotations, so this fills all 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 100% with descriptions for all parameters. The description adds context around the confirm parameter (permanence) but does not add new meaning beyond the schema, so a baseline 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 opens with 'Permanently DELETE one brand proposal from a project,' clearly stating the action and resource. It distinguishes itself from sibling tools like update_brand_variation and reorder_brand_variations, making the purpose unmistakable.

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?

Explicit guidance is provided: when to use update_brand_variation instead, when to follow with reorder_brand_variations, and when to read list_client_comments first. This gives clear when-to-use and when-not-to-use context.

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 covers all key behavioral traits: it OVERWRITES the stored order, takes effect on next view, rejects partial lists with a 400, requires kits:write scope, and returns the new order. This exceeds expectations for a mutation 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?

The description is detailed but every sentence contributes new information: purpose, client-view impact, overwrite warning, constraint/error, id source, and auth. It is front-loaded with the main purpose and flows logically. A minor typo ('directions' instead of 'variations') and slight verbosity keep it from a 5.

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?

Even without output schema or annotations, the description thoroughly explains behavior, errors, auth, and id sourcing. It covers the critical requirement to list all variations exactly once. It doesn't specify a formal response structure, but it mentions the return order, making it sufficiently complete for this operation.

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 schema already explains both parameters with good descriptions. The description adds value by telling users where to obtain variationIds (from add_brand_variation or a previous call) and reinforces the 'exactly once' requirement, providing context beyond the 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 clearly states the action ('Set the order the client meets the directions in') and identifies the resource (brand variations). It distinguishes itself from sibling tools like add/update/remove by focusing solely on reordering, even explaining the share page impact.

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 provides strong usage context: the order is a deliberate decision, and every variation must be listed exactly once, with partial lists rejected. It also references add_brand_variation as a source for ids. However, it does not explicitly state when not to use it or name alternatives, so it falls short of a 5.

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 discloses permanence ('cannot be brought back to life'), token behavior, side effects (project/variations/comments survive), the confirm requirement, and the required scope ('kits:write'). This is comprehensive behavioral transparency.

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 dense but not bloated; each sentence provides unique information, from URL behavior to the alternative tool. It is front-loaded with the core purpose and does not waste words, maintaining clarity and efficiency.

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?

Despite no output schema or annotations, the description covers decision-relevant context: permanence, when to use, what is preserved, and required scope. An agent has enough information to select and invoke the tool 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 baseline is 3. The description adds value by explaining that confirm: true is required and without it nothing changes, and that projectId is an owned brand project id from list_brand_projects (already in schema). The extra context about confirm's effect justifies a slightly above-baseline score.

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 function: 'Withdraw the client's access permanently' and specifies the resource (client share link). It distinguishes from sibling update_brand_share by naming it as the reversible alternative, making the specific purpose unambiguous.

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 gives when to use: 'for a link that leaked or an engagement that ended' and when not to: 'Reach for update_brand_share with enabled: false instead when the client should see it again later.' This is an explicit alternative with rationale and context, far exceeding basic guidance.

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 full burden and exceeds it: it discloses the return format ('dated raw results and nothing else'), non-behaviors ('does not score, rank, decide whether a collision is real, or constitute trademark clearance'), the required scope ('naming:read'), and the 20-search limit. This is rich, honest behavioral disclosure.

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 the core action, then expands with purpose and limitations. Every sentence earns its place: purpose, authorship, output scope, follow-up action, alternative tool, and auth requirement. 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?

Despite no output schema, the description fully explains what to expect (dated raw results only) and how to proceed (attach to board via move_name_candidates). It also covers the scope requirement and the domain alternative, making it complete for an agent to select and invoke 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 100%, so baseline 3 applies. The description adds meaningful context by explaining that the agent authors the queries and is limited to 20 tasks, and emphasizes query purpose ('Write it for the specific risk you are testing'), which supports correct use of the query field beyond the schema's literal description.

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 uses a specific verb ('run web searches'), names the resource ('a candidate name'), and enumerates concrete risk types (collision, market context, meaning, unfortunate readings, negative associations, official registers). It clearly distinguishes from siblings by naming check_domains as the alternative for domain/DNS evidence.

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 states when to use this tool ('you know what would disqualify this particular name'), what it covers, and an explicit exclusion: 'For domain registration and DNS evidence use check_domains instead.' It also clarifies that it is not trademark clearance, hedging against misuse.

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 fully discloses key behaviors: it candidly admits 'runs no server-side search,' explains that `query` is echoed back, states the ordering is neutral, and notes the output is the entire catalog rather than a filtered set. It also declares 'Read-only and free,' which is essential safety information for an agent. This goes far beyond a generic tool description.

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?

Although longer than a typical one-liner, every sentence earns its place: the first sentence front-loads the core action, subsequent sentences handle the misleading name, usage guidance, comparison, follow-up, and safety. The structure flows logically from what → name caveat → when → alternatives → next steps, with no filler or redundancy.

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?

Despite the absence of an output schema, the description specifies exactly what will be returned (moodSummary, vibeTags, tags, audience, font/palette glimpse) and what the agent should do next (pick 1-3, then get_design_md or apply_theme). The tool's full behavior—including its limitations and relationship to siblings—is captured, making it complete for an agent to select and invoke 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?

The schema already describes `query` as the brief with an example, so baseline coverage is high (100%). The description adds meaningful nuance by explaining that `query` is not sent to a matcher but 'echoed back to keep your brief in context,' clarifying its actual role. This extra semantic context is valuable, though not transformative since the schema already handles the basic meaning.

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 first sentence states a specific action—'Return the entire catalog at once, unranked, as compact summaries'—and enumerates the contained fields, making the tool's function unmistakable. It also explicitly distinguishes itself from the sibling tool list_themes by contrasting unranked/full versus ranked/paged, so there is no confusion about its role.

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 gives explicit when-to-use guidance: 'Use it when the brief is subtle or cuts across categories and you would rather weigh every option than trust a ranking.' It also names the alternative, 'Prefer list_themes when the brief maps cleanly onto a use case or search phrase,' and clarifies the difference. Follow-up steps (get_design_md, apply_theme) further complete the usage picture.

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 an excellent job: it discloses the shared quota system (daily, burst, fair-share, provider-cooldown), the meaning of a 429 response, the permission requirement (naming:read), and the caveat that results are not a legal verdict. This is rich behavioral context beyond merely stating the operation.

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 with no wasted words: the first states the core function, the second covers quota behavior, and the third covers permissions and result caveats. Information is front-loaded and each sentence 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?

Given the tool has 4 parameters, no output schema, and no annotations, the description provides solid context: purpose, constraints, quota, permissions, and result interpretation. It doesn't describe the return format, but for a search tool with no output schema, the description is quite complete. Minor gap is lack of pagination or response shape details.

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 schema already documents all parameters. The description adds minimal extra meaning beyond what's in the schema, only reinforcing the optionality of Nice classes and the 'owned naming candidate' context. This aligns with the baseline score of 3 when schema does the heavy lifting.

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 specific action: 'Screen one owned naming candidate against EUIPO's verbal-element register' with optional Nice class filtering, which distinguishes it from sibling tools like search_name_evidence and check_domains. The verb 'screen' and the resource (EUIPO verbal-element register) make the purpose unambiguous.

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 when to use the tool (when you have a naming candidate to check against EUIPO) and sets expectations about results being preliminary evidence. However, it does not explicitly name alternative tools or provide exclusion criteria, so it falls short of a 5 but provides clear context.

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 full burden and excels: it discloses that the operation replaces the entire context (omitted fields are deleted), explains the deliberate rationale, notes refusal of under-length product descriptions and over-long strings, and states authentication requirements. This is thorough behavioral disclosure.

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 six sentences, front-loaded with the purpose, and every sentence adds critical information: replacement semantics, rationale, safe editing workflow, validation rules, and auth. No wasted words; structure is logical and easy to scan.

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?

Despite having 9 parameters, nested objects, and no output schema or annotations, the description covers purpose, destructive behavior, editing workflow, validation constraints, and permissions. This makes it highly complete for a complex write operation, even without describing 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 coverage is 100%, so baseline is 3. The description adds meaningful behavioral semantics beyond the schema: product must be a real sentence (not just a label), omitted fields are deleted, and bounded strings are refused by name rather than truncated. This enriches parameter understanding but doesn't detail every nested field since the schema already does.

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 it stores product context for later proposals and explicitly says it 'REPLACES the whole context', which distinguishes it from the read-only get_project_context and other project tools. The verb and resource are specific and unambiguous.

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 tells users the safe way to edit: call get_project_context first, then send the whole object back with changes. It also specifies the required kits:write scope versus kits:read for reading, providing clear when-to-use and alternative guidance.

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 full burden and excels: it discloses read-only page behavior, open access and password need, idempotent re-call, destructive rotate side-effect, and the requirement for kits:write scope. This is comprehensive behavioral disclosure.

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?

While dense, every sentence earns its place: purpose, behavior, security, idempotency, precondition, and scope. The structure is logical and front-loaded with the core action, with no filler or redundant content.

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 no output schema and no annotations, the description fully covers what is needed: the return value (URL), preconditions (add variations), side effects (rotate breaks links), security advice, and authorization scope. It is complete for a tool with this complexity.

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?