Tseha

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

With only readOnlyHint in the annotations, the description carries the full behavioral burden and delivers thoroughly: it confirms read-only semantics, discloses exact-match case-sensitive name lookup with a not-found error instead of near matches, warns about provenance of LLM-generated records to treat as unverified, and documents project-scoped error behavior including plan errors retrying cannot clear.

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?

Six sentences, each earning its place. The key purpose and read-only safety statement are front-loaded, followed by param semantics, provenance caveat, and routing rules — no filler and no duplication of schema 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?

For a two-parameter tool with no output schema and only readOnlyHint by design, the description fully covers what is returned, when to call it, how to prepare inputs, error outcomes, and provenance caveats. An agent can select and invoke this tool correctly from the description alone, with the 100%-covered schema providing remaining parameter-level detail.

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 meaningful context above — name must be exactly as returned by list_components or search_components (case-sensitive, no package prefix, no near-match fallback) and recommends resolving the name first when in doubt. This is useful but incremental beyond the already-rich schema text.

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-plus-resource: 'Returns the full specification for one component' and enumerates the delivered contents (import path, props schema, usage example, anti-patterns, when-to-use notes, Figma spec, dependencies). It also distinguishes itself from sibling tools by naming what it is not for: enumerating components and per-version changes.

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 when-to-use guidance is included: 'Call it before writing code that uses a component' so props and import paths come from the design system instead of memory. It also gives explicit alternatives with conditions — use list_components to enumerate, get_component_updates for version changes, and search_components to resolve a guessed name before calling this 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?

The readOnlyHint annotation is reinforced with 'Read-only: it reports an upgrade, it never performs one,' and the description goes further by disclosing edge-case behavior (passing the latest version returns an empty change set) and the plan-dependent error. It also surfaces error behavior for an invalid project_id instead of silently returning data. No contradictions with 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?

Seven sentences, each carrying non-redundant information: core result, read-only nature, use cases, version syntax, empty-set behavior, distinct-from alternatives, and plan requirement. The core purpose is front-loaded in the first sentence, and no filler or repeated schema content exists.

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 2-parameter tool with no output schema, this is as complete as needed: it explains the result shape, exact parameter syntax, source of truth for parameters, error conditions, and feature requirements. An agent can call this tool correctly on its first attempt.

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 critical semantic detail to both parameters: current_version must be an exact semver without 'v', '^', or '~', and project_id is a UUID from list_projects that cannot be guessed. It also clarifies the connection between the two parameters ('Changes are computed against this project's active package, so current_version must be the version of that package'), which the schema alone does not establish.

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 precise verb-resource pair: 'Returns per-component breaking changes and a migration guide between an installed version ... and the latest published version.' It clearly differentiates this from siblings by naming what it is not ('not a per-component changelog and not a current spec') and pointing to get_component and list_packages as the alternatives.

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

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

Usage context is explicit: 'Use it when planning or reviewing a component-library upgrade, or before bumping the package version in a manifest.' It also defines exclusions and alternative tools, and states a hard prerequisite (update tracking Team plan) with the failure mode on lower plans. An agent can decide to use this tool vs others without ambiguity.

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

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

Annotations only declare readOnly, but the description discloses important behavior: full sections can be long, inventing a section id returns a not-found error, project_id is not guessable and must come from list_projects, and that out-of-organization ids return an obfuscated error. It also clarifies that returns prose rules, not structured data. This adds considerable transparency beyond the 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 compact yet dense, with each sentence adding a distinct behavioral or usage fact. It is front-loaded with the primary purpose and the 'Call it before' timing, then narrows down to workflow and alternatives. It carries no fluff or repetitive schema details, though the 'Read-only' is already in annotations; that duplication is minor.

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 that there is no output schema, the description sufficiently explains the return behavior (index first, then section content) and error cases. It also covers prerequisites (project_id UUID, no guessing ids), constraints (limit to needed sections), and distinguishes prose rules from the data returned by sibling tools, so an AI agent can invoke the tool correctly and interpret 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?

Even though schema coverage is 100%, the description adds substantial semantic value: section ids must come from the index, the framework parameter should be translated to a 'framework:' section prefix, and project_id is specifically a UUID from list_projects that resolves the org and controls which sections appear. This enrichment helps an agent select and reuse parameters correctly.

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 returns the organization's development standards: coding conventions, project structure, and framework-specific rules, with a specific verb 'returns' and resource. It also distinguishes itself from siblings by name, noting that get_style_tokens should be used for visual values and get_component for component APIs.

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

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

Usage guidance is explicit and comprehensive: 'Call it before any code review or review' identifies the right moment to use it; 'Call it first without section' describes the two-step index-and-select workflow; and it tells the agent to request only needed sections and explicitly flags that the framework argument is deprecated. It also names direct alternatives for different data types, showing when not to use this 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?

Beyond the readOnlyHint=true annotation, the description discloses that the tool returns no token values, that style assignment is project-scoped with no organization-level fallback, and that a project with no style returns a null style with a note rather than an error. This is meaningful behavioral context that the annotation does not 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 front-loaded and the core return semantics are stated immediately. The final sentence is useful but dense, mixing scoping rules with edge-case behavior; it is still economical and every 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?

For a tool with one parameter, no output schema, and a safe annotation, this description is complete: it names the return fields, clarifies the absence of token values, names the recommended next tool, and covers the most relevant edge case. Nothing needed to call it correctly is left out.

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 describes project_id at 100% coverage, so the baseline is 3. The description adds useful semantics by explaining that project_id is not a plain filter: styles are per-project, sibling projects can differ, and an unassigned style produces a null-style result. That extra meaning justifies moving above baseline without over-explain

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: 'Returns metadata for the project's active style,' then lists exactly what is returned: name, Figma file key, last synced time, and token count per category. It also names the sibling get_style_tokens, so the agent can distinguish this tool without reading other definitions.

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 says 'Use it to inspect the project theme, or to learn which categories are populated before requesting values; call get_style_tokens for the values themselves.' This gives explicit usage context and names the alternative, so the agent knows when this tool is 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?

Beyond the read-only hint, the description discloses non-obvious behavior: omitting category is equivalent to 'all', 'all' returns the largest response this server produces, and an unconfigured project returns an empty token list with a note rather than an error. It also details plan/access error behavior for project_id, which is exactly the kind of context a caller needs.

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 compact but information-dense paragraph. Each sentence earns its place: the first states the core return value, the second reinforces the read-only nature and primary intent, the third clarifies argument semantics, and the final covers alternatives and error behavior. No filler words, no 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?

With two params and no output schema, the description covers everything a caller could need: what tokens are, how category behaves, what the largest response is, how a missing style manifests, and how project_id errors appear. The inclusion of empty-list behavior and access-denied error messaging is thorough for a read-only 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?

Even though schema coverage is 100%, the description adds meaning that the schema alone does not: the category omission behavior ('behaves the same as all') and the project_id guidance ('not the project name, title, or slug... Fetch it once and reuse the same id', plus access/plan error scenarios). This significantly enriches what an agent knows before calling.

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 verb 'Returns' and the resource 'design tokens with their names, values, and token paths.' It stands out from siblings by explaining that get_style is for category discovery and get_standards is for coding conventions, so an agent can immediately tell this tool APIs apart without opening schemas.

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 explains when to use it ('source exact visual values for styling instead of inventing hex codes, spacing, or radii'), when to use a single category, and names alternatives: 'Use get_style first if you only need to know which categories exist, and get_standards for coding conventions, which are not tokens.' A clear set of conditions.

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

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

The readOnlyHint annotation covers safety, and the description adds meaningful behavioral context beyond it: the tool is unpaginated, returns the entire catalog, may produce a large response, and project_id is not a display filter but selects assigned packages. It also discloses that different projects in an organization can legitimately yield different catalogs. No contradiction with 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 longer than average but every sentence earns its place: the core scope is front-loaded, followed by behavioral caveats, then explicit sibling routing. It communicates a lot of operational nuance without 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?

Given the simple signature, the read-only annotation, and the rich schema, the description is complete: it covers output content, size expectations, usage guidance, sibling routing, and project_id semantics. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the project_id schema entries already explain UUID usage, 'not guessable', error behavior, and package selection. The description essentially restates this package-selection nuance without adding substantially new parameter-level semantics 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 — 'Lists every UI component in the project's design system' — and enumerates what is returned (name, source package, import path, intended use). It also clearly differentiates itself from siblings by explicitly saying not to use it for finding by need (search_components) or for props/examples/Figma data (get_component).

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

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

It gives explicit positive guidance: use it to see what exists before building UI and to get exact component names. It also gives explicit alternative routing: search_components for need-based search, get_component for props/examples/Figma data. This leaves no ambiguity about when to invoke this tool versus its siblings.

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?

Beyond the readOnlyHint annotation, the description discloses a non-obvious behavioral trait: assignment and active-package status are per project, so the same organization package can be active in one project and absent in a sibling. This provides useful context that annotations alone do not convey. The 'Read-only' confirmation is consistent but redundant with the annotation.

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 organized with purpose, use case, alternatives, and parameter semantics all present, and each sentence earns its place. It is slightly longer than strictly necessary because the per-project semantics appear in both the schema and the description, but it remains efficient and 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?

For a simple one-parameter, read-only tool with no output schema, this description provides a fully sufficient picture: return fields, decision context, sibling routing, and the key per-project behavior. The output schema absence does not leave an information gap because the description enumerates the return fields.

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 project_id parameter schema already describes the UUID format, per-project semantics, error behavior, and plan limits. The description adds only framing ('the only argument', 'does more than filter'), which is helpful but adds minimal new meaning over 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 ('Lists'), the exact fields returned (name, version, description, active marker), and clearly differentiates from list_components and get_component. An agent can tell exactly what this tool does and how it differs from its 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?

Explicitly says when to use the tool ('to decide which npm package to import from', 'before calling get_component_updates') and what NOT to use it for, pointing to list_components and get_component as the alternatives. This is full usage guidance with no ambiguity.

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?

Beyond the readOnlyHint annotation, the description discloses meaningful behavioral traits: it is credential-scoped ('only the projects the calling credential may see'), it takes no arguments, its results are mandatory for subsequent calls, and it explicitly excludes components, packages, and tokens. This materially helps the agent predict 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 earning its place: output content, read-only and scoping, usage ordering, and explicit exclusions with alternative tools. It is front-loaded and dense without extraneous detail.

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 tool, this description covers what an agent needs: return shape, auth scoping, why it must be called first, and what it is not responsible for. No critical operational context is missing.

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

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

The input schema is empty, so there are no parameter semantics to clarify; the 0-parameter baseline of 4 applies. The description still confirms 'takes no arguments,' matching the schema without contradiction.

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 plus resource ('Lists the projects in this organization') and states exactly what fields are returned (id, name, framework). It explicitly contrasts with sibling tools like list_components, list_packages, and get_style_tokens, making the tool's scope 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 explicit usage guidance: 'Call it first in a session' and explains that the returned id is the project_id required by every other tool and that guessing it fails. It also names alternatives for components, packages, and tokens, so when-not-to-use is crystal 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?

Beyond the readOnlyHint annotation, the description discloses ranking behavior, the 10-result limit, relevance scoring, semantic-search fallback on lower plans with a null score, and empty-result behavior (empty list, not an error). This gives the agent realistic expectations about return values and plan-dependent behavior, and it does not contradict the 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 dense but not padded; each sentence carries a distinct piece of guidance: what it does, read-only nature, when to use it, query format, exclusions, plan-based fallback, and error behavior. It front-loads the core purpose and follows with necessary constraints and caveats.

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 there is no output schema, the description still covers the return shape, scoring behavior, empty behavior, and plan-dependent variations. It also covers the most important project_id hazards that could otherwise trip up an agent. The combination of annotation(s), schema coverage, and description leaves no critical gap for 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?

Although the schema already documents both parameters with 100% coverage, the description adds meaningful usage semantics beyond field names: queries must describe use case/need, not component names; project_id must be fetched from list_projects, is not guessable, must be reused, bounds results to a project, and can yield access-denied vs plan-specific failures. This materially helps correct invocation.

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: searching the components assigned to a project by use case/behavior/description, returning up to 10 ranked matches with a relevance score. It also explicitly distinguishes itself from get_component and list_components, so an agent can tell it apart without reading sibling schemas.

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 condition ('when you can describe what the UI must do but do not know the component name') and clear when-not-to-use guidance with named alternatives ('do not use it when the exact name is known... get_component is direct' and 'list_components' for a full catalog). The text also warns about free-text query semantics versus globs/props expressions.

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