Lexington

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

With no annotations provided, the description carries the full behavioral burden. It implies a read-only retrieval operation through 'Read before' and describes the content categories returned, but it does not state permissions, auth requirements, response format, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description front-loads the resource and then enumerates its contents without filler. The long single sentence and parenthetical roles list are dense and slightly hard to parse, but the information is purposeful.

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 retrieval tool with no annotations and no output schema, the description covers the return categories and the trigger for reading it. It still omits how to supply the theme parameter and does not mention permissions, auth, or output form, leaving meaningful 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?

There is one required 'theme' parameter and schema description coverage is 0%. The description only frames it as 'The theme's design system' and never explains what value the theme parameter expects, such as an ID, name, or identifier from list_themes, so the schema gap is not compensated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource, 'The theme's design system,' and enumerates what it returns: typography recipes, colour scale meanings, spacing rhythm, components, do/don't, and roles.json details. It does not explicitly distinguish itself from siblings such as get_guidelines or get_theme_setup, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear when-to-use guidance: 'Read before changing anything visual, reskinning, or aliasing the palette onto a host.' However, it provides no when-not-to-use guidance and does not name alternatives among the sibling 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?

No annotations are supplied, so the description carries the disclosure burden alone. "Read this first" and "how to install..." imply a safe, read-only documentation fetch, and "what not to change" hints that the content includes constraints, but nothing is said about return format, length, or whether the content is authoritative versus advisory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the imperative call-to-action front-loaded and the content scope immediately after. Every phrase carries information and nothing is padded.

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 zero-parameter, read-only documentation tool with no output schema, stating the subject matter and the primacy of the call is nearly all an agent needs. A brief note on what the response looks like (structured sections versus prose) would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description adds no parameter detail because none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (guidelines) and enumerates its contents: installing, filling and fitting Lexington sections into an Astro + Tailwind project, plus what not to change. That is far more concrete than the sibling names like get_skill or get_design, though it never explicitly contrasts itself with those 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?

"Read this first" is an explicit ordering instruction that tells the agent to call this before other tools in a session, which is meaningful routing guidance. It stops short of naming alternatives or stating when to skip it, so it is clear context rather than a full when/when-not rule set.

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 supplied, the description carries the full burden and does disclose non-obvious behavior: shared files are sent once rather than duplicated per section, tsx output has no props, html output has Tailwind classes expanded, and standalone sections are the only flat-exportable unit. It omits things like size limits on the response, ordering guarantees, or failure behavior for unknown ids.

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?

Information is front-loaded: the return contract first, then batching advice, then format semantics, then the parts caveat. It is dense but every sentence carries distinct payload or format information; the opening sentence is a fragment and the 'fundations' typo slightly hurt readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must explain returns and it does: the file set per section, the write path per file, shared-file deduplication, and the exact difference between the two flat formats. Combined with a fully documented three-parameter schema, an agent has enough to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description genuinely elaborates on 'format' by mapping each value to output shape and target frameworks, and by warning that only standalone sections exist for flat export. The 'have' parameter is not mentioned at all, so deduplication is explained only 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 makes clear that this tool returns sections together with every asset file each needs plus the write path for each file, and that shared files are de-duplicated. It is written from the payload's perspective rather than a leading verb, and it never names the sibling tools (search_sections, get_design, get_theme_setup) so an agent must infer the boundary from the schema's note that ids come from search_sections.

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?

"Ask for the whole page in one call" is an explicit batching instruction, and the format paragraphs give a clear decision rule keyed to the target framework (Next/Vite/Remix vs Vue/Svelte/plain HTML). It also states a hard limit — parts have no flat export — but gives no guidance on when to prefer this over get_design or get_theme_setup.

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 does disclose the composition of the payload (theme design skill + shared sections skill) and lifecycle guidance (once per project), which is real behavioral context. However it never says what is actually returned or what happens when the target already has a skill file, which matters for a tool whose output is written to disk.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence stating what it is and what it contains, plus one short ordering instruction. The nested parenthetical is dense but each clause earns its place; 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?

No output schema, and the tool's whole point is producing content the agent writes into a project, yet the return shape and the meaning/format of `theme` are unmentioned. The sequencing and payload composition are covered, but the definition is not complete enough for confident invocation on the theme argument.

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 description adds nothing about parameters: the `target` semantics already live in the schema (50% coverage), and `theme` — the sole required parameter — is never explained (e.g. whether it is a name or an ID from list_themes). For a required parameter with no schema description, the description should compensate but does not.

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 companion skill for a theme, to write into the project" names a specific resource (a skill bundle) and its intended use, and the parenthetical enumerates contents (typography, colour, spacing, components, shared Lexington sections skill). It is distinguishable from get_design/get_guidelines by being a bundle emitted into the project rather than a live query, though the contrast is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Call once per project after the first get_sections" gives explicit ordering, cardinality, and a triggering event, and "without calling this server" clarifies the ongoing benefit. It stops short of saying when to prefer get_design or get_guidelines instead, so it lacks explicit alternatives/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 full burden; it does disclose that the result is files to write (tokens.css, Fonts.astro) plus two setup steps and that invocation is idempotent-per-theme. It says nothing about permissions, error behavior, or whether repeated calls differ, which leaves meaningful gaps for a setup/mutation-adjacent 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?

It is short and front-loads the frequency constraint, but the fragment style ("tokens.css and Fonts.astro to write") reads as notes rather than prose and forces re-parsing. Nothing is padded, yet the terseness costs clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter setup tool with no output schema, the description covers ordering and expected artifacts but omits the parameter format and any return-shape detail. It is roughly adequate, not 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 0% and the sole required parameter "theme" is a bare string with no documented format. The description never explains whether it takes a theme name, slug, or ID from list_themes, so the agent must guess and cannot compensate from 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?

"tokens.css and Fonts.astro to write, plus the two setup steps" hints that the tool returns theme scaffolding artifacts, but the phrasing is telegraphic and never states plainly what the call produces. The reference to get_sections gives some sibling differentiation, yet an agent still has to infer the resource shape.

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?

"Once per project, per theme" and "Call before the first get_sections for a theme" are explicit frequency and ordering rules that an agent can act on directly. There is no guidance on what to do if it was already called or on failure cases, but the core when-to-use is clear.

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

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

With no annotations, the description carries the full burden; it does disclose the return payload's fields, which signals a read-only enumeration, but says nothing about ordering, pagination, or whether the list is scoped to the account. For a zero-parameter listing call the risk is low, so this is adequate rather than rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the resource and its returned attributes, ending with the one actionable rule. Nothing is 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?

There is no output schema, so the description must convey return content, and it does by listing the per-theme fields. For a no-parameter list tool this is nearly complete, missing only ordering or count information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The schema is empty and fully self-evident.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (every available theme) and enumerates the attributes returned: target audience, visual personality, fonts, light/dark mode, and section count. It is clear this is an enumeration tool, though the verb is implicit and it never distinguishes itself from siblings like get_theme_setup or get_design.

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?

"Pick one theme per page" gives a downstream usage constraint, which is genuinely useful, but the description never says when to call this versus get_theme_setup or get_design. The when-to-use is implied by the resource name only.

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 supplied, so the description carries the whole burden. It does usefully disclose the return shape (id, group and a one-line description), which matters because there is no output schema. It says nothing about result limits, pagination, ranking behavior, or whether the search is fuzzy, so an agent cannot predict result volume.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with purpose, then return shape, then the handoff instruction. Nothing is 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?

For a five-parameter, all-optional search tool with full schema coverage, the definition supplies purpose, return fields, and the follow-up call, which is most of what is needed. The absence of paging/ranking information is the only meaningful gap, and there are no annotations to compensate.

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 every parameter, including the mode enum and the group list, is already documented in the schema; the baseline is 3. The description adds only a loose phrase about searching by 'role and description', which does not map cleanly to any parameter (no role parameter exists) and could mildly confuse.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (Find) and resource (sections), and states the axes it searches on (role and description). It also distinguishes the tool from the sibling get_sections by explaining that this tool produces ids that get_sections consumes. It is not a formalism, but it is enough for an agent to tell the two apart.

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 an explicit downstream workflow ('Use the ids with get_sections') and implies discovery-style usage. It does not state when-not to use it or how it differs from list_themes/get_design, but the search-then-fetch relationship with its main sibling is clear.

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