Systra Tools

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description builds on that with behavior those hints cannot convey: the response names extra dependencies with install commands, and without a premium key only free components resolve while other names return a key-acquisition notice. That gating and partial-success behavior is exactly what an agent needs to interpret a non-source response.

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

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

Three sentences, front-loaded with what is returned, then dependencies, then routing and gating. The dependency sentence is dense and stacks react, framer-motion, lucide-react, gsap and three in one clause, but each clause carries information an agent would otherwise have to discover by trial.

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

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

For a single-parameter read tool with no output schema, the description covers return payload, non-source extras, dependency install needs, the alternative tool, and the unauthenticated fallback. Nothing an agent needs in order to call this correctly or interpret its result 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 single parameter's schema already explains the source of the name, case-insensitive matching, and an example. The description's 'once you know the exact name' reinforces exactness but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Returns the complete, copy-ready React/TSX source of one component as designed.' It also states the payload goes beyond source (notes on images and extra files), which lets an agent distinguish this from sibling get_component_styled without opening either schema.

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 trigger ('Use it once you know the exact name') and names the alternative with the condition that selects it: 'use get_component_styled instead when the component should take on an extracted brand style.' It also states the freemium boundary and that list_components/search_components mark which names are free, so the agent knows what to try when a call fails.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context—it returns source, style tokens, mapping instructions, and current colour values, and explicitly says the server does not rewrite code—but the phrase 'Same premium rule as get_component' is an opaque cross-reference that is not self-contained.

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 return contents and the usage decision, and every sentence adds useful information: what is returned, when to use it, what the server does not do, and a shared rule reference.

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, but the description enumerates what the tool returns (source, tokens, mapping instructions, current colour values), which is sufficient. Combined with full schema coverage for both parameters, an agent has what it needs 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?

Schema coverage is 100% and both parameters are fully documented in the schema, so the baseline is 3. The description does not add syntax or format details 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?

The description states a specific verb and resource ('Returns one component's source together with the tokens of a brand style') and explicitly distinguishes itself from the sibling get_component by naming the alternative and the condition that selects it.

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 routing guidance: 'Use it instead of get_component when the result should match a specific brand.' The alternative and its selection condition are named directly, leaving no inference needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious context beyond that: 'The server renders nothing; you edit and export the file' — a workflow constraint an agent would otherwise assume wrong. No mention of size limits or auth, keeping it short of a 5.

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

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

Three sentences, no filler, and the return contents are front-loaded before the usage note. Every clause conveys information the agent needs.

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, the description must explain what comes back — and it does, naming the HTML file, export script, and edit rules. Combined with the 'server renders nothing' caveat, an agent has everything needed to call and use 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 description coverage is 100%, with slug documented as coming from list_posts and lang as an optional enum with English default. The description adds nothing about either parameter, so the schema carries the full burden and baseline 3 applies.

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

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

States a specific verb and resource ('Returns one post template as working instructions') and enumerates the payload: the full HTML file, an export script, and the change rules. This clearly separates it from list_posts and from the get_component/get_recipe/get_style siblings that fetch other asset types.

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?

'Use it after list_posts' gives an explicit prerequisite and sequencing hint. It doesn't state when-not-to-use or name alternative retrievers (get_component, get_recipe), but the resource-specific naming plus the list->get pattern makes the routing obvious.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: non-free sections are gated without a premium key, and the response is long because it includes several complete components.

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 return value, followed by the optional style behavior, access limitation, and response-size note. Every sentence adds useful information without repetition 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 read-only tool with no output schema, the description explains the return contents, optional style behavior, premium-key limitation, and expected response length. An agent has enough information to call it correctly and anticipate the response.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description reinforces that style adds brand tokens and adaptation instructions, but does not add substantial syntax or format details 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 uses a specific verb and resource ('Returns one page recipe') and details exactly what the response contains: ordered sections, purposes, composition file, and full source. This distinguishes it from list_recipes by emphasizing a single complete recipe rather than a list.

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 explains that passing style adds brand tokens and adaptation instructions, which is useful parameter usage. However, it does not explicitly state when to choose this tool over siblings like get_component or get_component_styled, nor does it give when-not-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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral detail: the payload is exhaustive ('every design token') and DESIGN.md is capped at 4000 characters, which tells the agent to expect truncation. It does not say what happens if the slug is unknown or whether output is cached, keeping it just short of a 5.

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

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

Two sentences, both earning their place: the first front-loads what is returned, the second handles usage and routing to the alternative. No filler or repetition of the title.

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, but the description compensates by enumerating the returned token categories and the 4000-character DESIGN.md cap. With only one required, fully documented parameter and complete annotations, an agent has everything needed to call 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% and the single slug parameter is documented in-schema as 'exactly as listed by list_styles'. The description adds nothing about the slug (no format, case sensitivity, or error behavior), so the schema does all the work and the baseline 3 applies.

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

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

States a specific verb and resource ('Returns every design token of one extracted brand style') and then enumerates the token categories returned (colours, fonts, spacing, radii, CSS variables, DESIGN.md). It also explicitly distinguishes itself from the sibling get_component_styled, so an agent can pick between them 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?

Gives both a positive use case ('theme your own code or set up a design system') and an explicit alternative with its selecting condition ('use get_component_styled when you want one specific component already paired with the style'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds non-trivial operational context beyond that: 'No parameters, works without a key', telling the agent no auth setup is required before calling. It does not discuss rate limits or result ordering, which keeps it below a 5.

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

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

Three short sentences, front-loaded with what it returns, then when to use it, then the auth/param note. Every sentence carries information the agent needs; nothing is 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?

There is no output schema, yet the description compensates by enumerating the returned fields (slug, title, component count), so the agent knows exactly what comes back and how to chain into list_components. Authentication requirements are also stated. Nothing material is missing for a zero-argument read 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?

Zero parameters yields a baseline of 4, and the description confirms the absence explicitly ('No parameters') so the agent will not hunt for a required argument. No additional parameter meaning is available to add.

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

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

States a specific verb and resource ('Lists every component category of the Systra Tools library') and goes further by naming the return fields (slug, title, component count), which no sibling list_* tool does in its name. An agent can immediately tell this apart from list_components, list_styles, etc.

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

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

Gives an explicit trigger ('start here when the user names a kind of page part (hero, pricing, footer) instead of a component') and an explicit next step ('then pass the slug to list_components'). Both the when-to-use condition and the follow-on alternative are named, leaving nothing to inference.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing the output format, that names are returned without source, that no API key is needed, and what changes when a key is absent ('free' marks). It does not address handling of the >600-item unfiltered listing (truncation or pagination), which is the only real behavioral gap.

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 short sentences, front-loaded with what it returns and where to go next. Minor redundancy between 'lists component names' and 'one line each with the name and the category slug', but 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 single-optional-parameter read tool with full annotation coverage and no output schema, the description supplies the return shape, the auth nuance, and the sibling routing. An agent has everything needed to call it 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% and the category parameter already documents slugs, examples and the omit-to-list-all behavior; the description only restates 'optionally limited to one category'. With the schema doing the heavy lifting, baseline 3 applies — no extra syntax or edge-case meaning is added.

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?

Specific verb + resource ('Lists component names'), plus the exact output shape ('one line each with the name and the category slug'). It explicitly distinguishes itself from search_components and get_component, so the agent can pick between siblings without opening a schema.

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 the browse-first use case ('browse a category before choosing') and the exclusion with a named alternative ('use search_components instead when you already have a keyword'). It also hands off to get_component once a name is chosen, covering the full workflow.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, but the description adds genuinely useful context: the returned fields and permanent URL usability as src, page size of 100, and the premium-key gating that silently narrows results. It stops short of saying how to detect the last page or why 'a few videos' appear in an image listing.

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?

Roughly four sentences, each doing distinct work: what it returns, how to filter, when to use vs the sibling, and the key limitation. Front-loaded with the resource and the result shape.

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 carries the return-shape burden and does so (URL, title, album, format). Combined with pagination size and quota gating, an agent has enough to call it 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?

Schema coverage is 100% and the album enum values are fully enumerated there, so the description only restates filterable dimensions (album, format) and the 100-per-page cap. Baseline 3 is appropriate; no added syntax or 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?

States a specific verb+resource (lists images and a few videos) scoped to the Systra Tools media library, and names what each result carries (permanent URL, title, album, format). Clear enough to separate from search_images without opening the schema.

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

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

Gives an explicit routing rule: browse an album with this tool, use search_images to find a motif by keyword. It also states the access limitation (premium key yields only free images, three per album), which is the main precondition an agent needs.

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

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

Annotations already declare readOnly/idempotent/non-open-world, and the description adds real context beyond them: templates are single HTML files that can be rebuilt and exported as image or video, and it names the fields each entry carries. It omits nothing critical for a non-destructive read; minor gap is no note on result size or ordering.

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 short sentences, front-loaded with what is returned, then the filter, then the downstream step. Nothing repeats structured fields and no sentence is 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?

A parameterless-filter list tool with full schema coverage and rich annotations needs nothing more; the description covers return shape, filter behavior and the follow-up call. No output schema is required because the returned fields are stated inline.

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% (baseline 3), and the description adds value on top by giving concrete query examples and stating the searchable dimensions. It slightly understates the schema's matching rule (slug, name, purpose or family) and never mentions the family enum, so it isn't a full 5.

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

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

States a specific verb (lists) and resource (Instagram post templates, 1080x1350) and enumerates the returned fields (slug, name, family, needs-imagery), which distinguishes it from get_post and the other list_* siblings by resource.

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 places the tool in a workflow: 'Use it to pick a slug for get_post,' and shows how to filter with query examples ('quote', 'statistic'). It does not compare against the other list_/search_ siblings, but the resource boundary is clear enough that an agent won't confuse them.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value by disclosing what results contain ('number of sections and a short purpose') and the workflows it belongs to (list then get_recipe). No pagination or result-count behavior is mentioned, which keeps it below a 5.

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

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

Three sentences, front-loaded with the definition, then query usage, then the usage/next-step guidance. No filler, and each sentence carries distinct 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 single-optional-parameter, read-only listing tool with full annotation coverage and a fully documented schema, the description covers everything an agent needs: what it returns, when to choose it, and the natural follow-up call. No output schema exists, and the description compensates by describing the per-item 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%, so the matching rules (every word must appear in slug, title, description or section names; no query lists everything) are already documented. The description still adds useful semantics by naming the facets to search on (industry, purpose, section) and supplying concrete example terms like 'hotel' and 'pricing'.

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?

Names a specific verb and resource ('Lists curated page recipes') and immediately defines the domain-specific term as 'proven section sequences for complete landing pages' with concrete examples (SaaS, coaching, hotel). The 'whole page rather than one section' framing implicitly separates it from the component-listing 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 states the selection condition ('when the user wants a whole page rather than one section') and the follow-up step ('then call get_recipe'), plus how to use the query parameter with examples. It stops short of naming the sibling the agent should pick for a single section (presumably list_components), leaving that inference to the agent.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. The description adds a genuinely useful operational fact not in the annotations: 'Works without a key', which tells the agent auth is not required. It does not mention rate limits or maximum result size, but the default of 30 newest is carried 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?

Three sentences, front-loaded with what the tool lists and its returned fields, then search behaviour and downstream routing. No sentence is redundant and nothing is buried at the end.

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, but the description compensates by enumerating the returned fields and the default listing size context via the query parameter. Auth requirements and the follow-up tools are both covered, so an agent can call this and act on the result without further inference.

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 earns an extra point by supplying concrete example queries ('bakery', 'Inter') that demonstrate the accepted value space (site name, domain, colour, font) more vividly than the schema's prose. Matching semantics (every word must appear) remain schema-only.

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

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

States a specific verb and resource ('Lists the brand styles extracted from real websites') and enumerates the returned fields (slug, site name, colours, font), which separates it cleanly from siblings like list_components or list_posts. An agent knows exactly what this tool returns without opening the schema.

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 routes the agent downstream: 'Use it to find a slug for get_style, get_component_styled or get_recipe', naming three concrete alternatives. It also explains when to use the query parameter ('for example bakery or Inter'), covering both the default and filtered modes.

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

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

Annotations already cover read-only, idempotent, closed-world safety. The description adds real behavioral detail beyond them: case-insensitive substring matching, single-term constraint, and the naming convention (English PascalCase) that affects match quality. It does not discuss result ordering or limits, so not a 5.

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

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

Four sentences, each doing distinct work: capability, when-to-use, matching hint, next step. The capability statement is front-loaded with 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?

With no output schema, the description correctly states what is returned (names plus category slug). Combined with the follow-up pointer to get_component and the match semantics, an agent has everything needed 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?

Schema coverage is 100%, so the schema already documents the query parameter and its match targets. The description still adds value by stressing one term, case-insensitivity, and that short English words match best—guidance the schema lacks.

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

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

States a specific verb (finds) and resource (components) plus the exact match basis (name or category) and the return content (names with category slug). It is clearly differentiated from list_components and 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?

Explicitly says when to use it ('when you know roughly what you need'), names the alternative (list_components for a whole category), and prescribes the follow-up (get_component for source). This is a complete routing instruction.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description correctly spends its words elsewhere: results are all AI-generated, 100 per page, returned as permanent URLs, and licensing limits the corpus for non-premium keys. The language note (titles/tags English, album keys German) is non-obvious operational context an agent could not infer from 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?

Three dense sentences: what it matches and returns first, then the routing versus list_images, then the licensing caveat. No restatement of the name or title, and 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 two-parameter search with no output schema, the description covers matching semantics, return payload (permanent URLs), page size, and corpus restrictions. It stops short of saying whether results are relevance-ordered or how to detect the last page, a minor gap for a paginated 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%, so both parameters are already documented and the baseline would be 3. The description adds value beyond that by clarifying the AND-match semantics across multiple fields and by noting that album keys are German while titles/tags are English, which materially affects how to phrase a query.

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

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

States a specific verb and resource ('Finds images in the media library') plus the exact matching rule: every word of the query must appear in title, tags, file name or album. It also names the sibling it is not ('use list_images to browse a whole album'), so an agent can separate it from the browse tool without opening either schema.

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

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

Gives an explicit when-to-use with concrete examples ('red dress', 'laptop desk', 'misty forest') and an explicit alternative with its own condition (list_images for browsing a whole album). It also discloses a prerequisite that changes results: without a premium key only free images are returned.

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