Ordkort

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

Annotations only give the generic write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuine behavioral context beyond that: the tool returns a link, the recipient must consent before the deck is added, and the link stays valid for a year. It does not mention auth or permission requirements, but the consent-and-longevity details are valuable.

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

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

Three sentences with the core action front-loaded. Most sentences earn their place, though the middle sentence about picture/cover URLs is dense and slightly muddled in structure.

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

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

For an 8-parameter creation tool with no output schema, the description covers the key unknowns an agent needs: the return value (a link), the consent flow, link lifetime, and the image parameter conventions. Remaining gaps around the many card sub-fields are handled adequately by the schema.

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

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

Schema coverage is 50%, so the description must carry weight for the undocumented half. It usefully explains that pictures are https addresses (image_url) sourced from find_pictures and that cover_url is a small square-cropped image shown instead of the emoji. However, it adds nothing about title, level, native/target, or the card sub-fields, so it only partially compensates.

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 ('Makes a deck of up to 500 cards and returns a link'), and clarifies what the link does when opened. It is clearly distinguishable from find_pictures (which supplies pictures) and list_languages, though it does not directly contrast with the similarly named create_design sibling.

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 is implied through the workflow hint that pictures come from 'find_pictures' and language codes come from list_languages, but there is no explicit statement of when to use this versus create_design or when not to use it. The agent must infer the intended 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 only give write/non-idempotent/non-destructive. The description adds substantial behavior the annotations cannot convey: scripts and event handlers are stripped, remote images are fetched once with a cap of 8, the design is only applied if the user agrees, and the response may include notes about what will not work as intended.

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?

Front-loaded with purpose and the confirmation flow, followed by the prerequisite and then dense but useful template details. It is one long run-on paragraph, but the volume is justified by 0% schema coverage; little of it 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?

For a complex, mutation-style tool with no output schema and no parameter descriptions, this covers template syntax, CSS variables, image fetching limits, sanitization behavior, and the confirmation/preview flow. An agent has enough to author a valid design call without opening the sibling design_guide.

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%, so the description carries the full burden. It thoroughly explains front_html, back_html (template syntax, conditional blocks, image binding), card_css and site_css (their scopes and available CSS variables), but says nothing about the required `name` parameter beyond its obvious meaning.

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

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

States a specific verb and resource: it creates a visual 'look' for Ordkort cards and returns a preview link with a confirmation step. This is clearly distinct from deck-related siblings like create_deck, though it never names an alternative to contrast against.

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 design_guide first' is an explicit, actionable prerequisite that most definitions lack. It does not state when *not* to use this tool or name any alternative path, so it stops short of full routing 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?

readOnlyHint and openWorldHint confirm it's a safe, non-network read, so the safety profile is covered. The description adds that the content concerns design/CSS context, but says nothing about what form the guide takes (prose, structured config, code examples) or its size, which matters for a pre-flight read.

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 compact sentence followed by a short imperative. Reasonably front-loaded and free of padding, though the first clause is a run-on list that could be tightened.

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 no-param documentation tool with readOnly annotations and no output schema, the description covers intent and the create_design prerequisite. It leaves the agent guessing about the guide's format and scope — e.g., whether it includes concrete CSS values or just conceptual naming — which matters for a tool whose sole output is its content.

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, so the baseline is 4. The description correctly signals the absence of inputs by framing this purely as reference material to consume rather than an operation with selectors or filters.

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 gestures at the content — card structure, fields/pictures templates can use, CSS variables and site parts — but never states a concrete verb like 'retrieves' or 'documents'. The title 'How to design a look' is vague, and the sibling create_design is only referenced as a prerequisite rather than contrasted.

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

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

Explicitly instructs the agent to 'Read it before create_design', which gives a clear when-to-use condition tied to a named sibling. However, it doesn't explain when NOT to use it or what other discovery tools (find_pictures, list_topics) offer as alternatives.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes further by disclosing the source fallback order, the ranking rule (title/tag matches first), the requirement to pass a bare word plus language, and what each result carries (image_url and credit). It stops short of rate limits, latency, or failure behavior, but adds substantial context 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?

Front-loaded with the resource and source chain, with the parameter instruction and return-shape note trailing. The middle sentence is a long run-on but every clause (source order, sort rule) earns its place; only minor tightening is possible.

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 compensates by naming the returned fields (image_url, credit) and their intended use. It also covers input conventions and the multi-source ranking, leaving little ambiguity for a correct invocation, though it omits fallback behavior when fewer sources match.

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 real meaning: the concrete example that "hus" in nb finds a house clarifies language-dependent lookup, and it cross-references list_languages for valid codes. That is more than the schema's own field descriptions provide.

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 (find openly licensed pictures for a word) and even enumerates the source chain — Wikimedia Commons, Pixabay, Openverse. It is trivially distinguishable from the deck/design siblings, none of which retrieve images.

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 is implied through the hint that each result has an image_url to put on a card, but there is no explicit when-to-use vs. alternative, no exclusion, and no mention of how it relates to siblings like create_design. The instruction to pass the bare word and its language is helpful but is parameter guidance rather than tool selection 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that the set is fixed and complete (exactly 60 languages) against a closed-world annotation, which is useful context, but it says nothing about ordering or format of the returned codes.

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?

A single compact sentence that front-loads the resource and the completeness count with zero wasted words.

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

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

For a zero-parameter enumeration with no output schema, the description adequately conveys what is returned (language names with codes). Ordering and exact code format are the only minor gaps.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing extra is needed or expected from the description here.

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 60 languages Ordkort teaches) and states the payload (their codes). It is a noun phrase rather than a verb+resource, and it does not explicitly distinguish itself from list_topics, but an agent can tell what it returns.

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?

There is no statement of when to call this tool or when to prefer an alternative such as list_topics. Usage is only inferable from the name and the payload description.

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 and openWorldHint=false, so the safety and closed-world profile is covered. The description reinforces this by calling the topics 'built-in', but adds nothing about ordering, count, or return shape.

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?

A single front-loaded sentence with the resource first and parenthetical examples doing real work. No filler or restatement.

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-param, read-only lister with no output schema, the description gives the agent enough to call it and interpret the result. It could say slightly more about what a 'topic' is used for, but nothing essential 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 tool takes zero parameters, so there is nothing for the description to disambiguate beyond confirming the call is argument-free. Baseline 4 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 identifies the resource (built-in topics for word lists) and the payload (their ids), so an agent knows it returns a static list. It does not use an explicit verb and only implicitly separates itself from sibling listers like list_languages.

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?

There is no statement of when to call this versus alternatives. Nothing tells the agent that this is the lookup to run before create_deck or ready_words, nor that the set is finite and needs no arguments.

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 and openWorldHint=false, so safety is covered; the description adds non-derivable behavior: that nouns and verbs are dictionary-checked, and that results can legitimately be empty for rare language pairs. That caveat is exactly the kind of trait an agent cannot infer from structured fields. It does not describe ordering, pagination, or how count interacts with availability.

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 the tool returns before the quality note and the empty-result caveat. The dictionary-checking sentence is the weakest link but still informs trust in the output. No filler or repetition of the tool name.

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

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

With no output schema and read-only annotations, the description carries the return-shape burden and does so by naming translations, forms, and examples, plus the empty-result case. What is missing is minor for a lookup: how the count default of 30 is applied when fewer words exist, and result ordering.

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 60%, with topic, native, and target documented and level/count carrying only enum/default metadata. The description reinforces that topic and level drive the lookup but says nothing about count, and critically does not disambiguate which language is the source (native) versus the produced word (target). Minimum-viable; it neither compensates for the coverage gap nor misleads.

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 concrete resource ('words already in Ordkort's shared bank'), scoped to a topic and level, and describes what each item carries (translations, forms, examples). It implicitly distinguishes itself from the lookup siblings list_topics/list_languages, which only supply the ids this tool consumes. It stops short of an explicit verb like 'retrieve', so it is clear rather than crisp.

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 fallback clause 'May be empty for a rare pair of languages; then write the words yourself' tells the agent what to do on an empty result, which is genuine usage guidance. However, there is no explicit statement of when to reach for this tool versus create_deck/design_guide, or of prerequisites such as needing a topic id from list_topics first. Usage is implied rather than spelled out.

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