IT-Schulungen.com

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds that it returns only a version/liveness signal and no course data, which is meaningful behavioral context; output schema exists so deeper return details aren't required.

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

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

Two short sentences: what it does first, then the constraint on when to use it. No filler, nothing repeated from the title or annotations.

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 diagnostic tool with an output schema and full annotation coverage, the description supplies everything an agent needs: purpose, usage constraint, and the negative guarantee about data returned.

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 and there is no parameter surface the description needs to explain. The description correctly implies a no-argument call.

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 (check reachability) and a specific result (reports version), naming the resource as this MCP server. The closing line 'It returns no course data' distinguishes it from every sibling, all of which deal with seminar/course data.

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 this only to diagnose connection problems' gives an explicit when-to-use and a restriction, and the note about no course data tells the agent when not to use it (i.e., for any actual data lookup, use a seminar_* 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?

Despite annotations already declaring a safe read operation, the description adds substantial behavior: cancelled/postponed/expired dates are filtered out, city type distinguishes virtual vs on-site, and the `seminar` field can be absent on lookup failure while dates still stand. It also warns explicitly that a missing `direct_booking` does NOT imply unavailability, preventing a real misinterpretation.

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 core behavior, then layered with interpretation rules. The status and timezone paragraphs are long but each carries non-obvious guidance (lead with 'guaranteed', convert UTC to Europe/Berlin before quoting). Some bullets could be tightened, but there is little true 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 6-parameter read tool with an output schema, everything an agent needs is present: filtering rules, timezone conversion instruction, how to interpret `status`, `direct_booking`, and missing `seminar`. No ambiguity remains about how to call or how to present 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%, so baseline is 3, but the description goes further: `from`/`to` are German calendar days with both bounds inclusive, and `from` defaults to today. That clarifies timezone semantics the schema leaves implicit, though `city`, `page`, and `limit` get no extra explanation.

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

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

The first sentence gives a specific verb and resource ('Lists the scheduled dates of a seminar') plus ordering ('soonest first'), which is far beyond the title restatement. It doesn't explicitly contrast with siblings like seminar_get, but the resource scope is unambiguous.

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

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

It states concrete operating conditions: past dates are never returned, an omitted `from` starts today, and an empty result means 'nothing scheduled' rather than 'seminar doesn't exist'. It is missing an explicit 'use this instead of X' alternative, but the usage context is otherwise 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds a genuine behavioral fact beyond them: the returned values are identifiers, not human-readable labels, which changes how the agent must use the result. It stops short of describing ordering or any edge cases, 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?

Two short sentences, zero waste. The purpose is front-loaded and the actionable prerequisite follows immediately, with the reason appended rather than buried.

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 zero-parameter lookup tool with an output schema and full annotations needs only to say what it enumerates and how to consume the result — both are present. Nothing an agent needs in order to call 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?

The tool takes zero parameters, so there is nothing to disambiguate; baseline is 4. The description usefully redirects parameter semantics to the downstream tool by noting that `seminars_search`'s difficulty filter expects an identifier.

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 ('the difficulty levels a seminar can be filtered by'), and the enumeration framing distinguishes it from sibling lookups like seminar_topics and seminar_locations. An agent can immediately tell this is a lookup/enumeration tool, not a search tool.

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

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

Explicitly prescribes the call sequence: 'Call this before passing `difficulty` to `seminars_search`', naming the exact sibling and the exact parameter it feeds. It also explains why the prerequisite exists (the filter takes an identifier, not a label), which is precisely the kind of routing information 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond that: markdown output, per-delivery-form pricing, `calculation_unit` and `offer_type` semantics, URL forwarding rules, and the fact that the server does not take bookings or enquiries.

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 what the tool returns and then adds operational guidance. It is somewhat lengthy and repeats the pricing-per-delivery-form concept, but every paragraph carries useful context for an agent handling prices and URLs.

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?

An output schema exists, so return structure does not need to be fully described, yet the description still provides crucial operational context about price presentation and URL handling. Combined with the 100%-documented `guid` parameter and read-only annotations, an agent has everything needed to call and interpret 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 description coverage is 100% and the single `guid` parameter is documented with an example in the schema. The description adds no additional meaning about the identifier itself, so the baseline of 3 is appropriate for a high-coverage 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 opens with a specific verb and resource — "Returns one seminar with its description, agenda and prerequisites" — and explicitly distinguishes it from `seminars_search`, which "carries the amounts alone." An agent can tell this is the detail-fetch tool for a single seminar.

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 a clear context for use (retrieving one seminar's full details) and routes users away from this server for enquiries or bookings. It also names `seminars_search` as the amount-only alternative and provides a fallback when the URL field is missing, but it does not explicitly say when to prefer this over sibling facet tools like `seminar_dates`.

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, openWorld and non-destructive, so the safety profile is covered. The description adds valuable behaviour beyond that: the catalogue is closed (a fixed set plus one virtual entry), and the absence of a city is a definitive negative signal. It doesn't cover return shape or how the optional query filter matches, leaving modest gaps.

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 core action is front-loaded in the first sentence, followed by two sentences that each add distinct value: catalogue scope, then the routing rule to seminar_dates. No restatement of the tool 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?

An output schema exists, so return values need not be described. For a zero-required-parameter, single-parameter lookup, the description supplies everything an agent needs: what the list contains, what it implies when a value is missing, and how it relates to the sibling tool.

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

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

Schema coverage is 100% and the single parameter already carries an example ('Frank') and default of null, so the schema does the heavy lifting. The description implies canonical naming ('however the customer spells it') but adds no matching semantics such as substring vs. exact or case sensitivity, so the baseline 3 holds.

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 places seminars are held at') and then bounds the scope precisely: a fixed set of cities plus a virtual classroom. An agent can distinguish this from seminar_dates or seminars_search without opening either schema, since the catalogue/registry nature is explicit.

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?

Names concrete usage scenarios ('where do you teach this?') and an explicit downstream dependency: check a place before passing it to seminar_dates. It also gives the negative inference rule — a city absent from the list has no dates regardless of spelling — which tells the agent exactly when this call is authoritative versus when to defer.

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?

Well beyond the annotations: it discloses that matching is semantic over the whole text, that results come by relevance, that the query string of the returned url must be preserved, that all prices are net plus VAT, and that a missing amount means price on request. The annotations already cover the read-only/idempotent safety profile, and no behavior contradicts them.

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 core rule, but the pricing passage is long relative to a search tool and reads as shared guidance rather than search-specific instruction; it dilutes the search mechanics an agent needs at call time.

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

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

Despite an existing output schema, it explains the fields that change agent behavior (topics for justification, prices with their per-unit meaning, url that must be surfaced verbatim) and points to seminar_get for what is included in the price. Nothing needed to invoke or interpret a 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 coverage is 100%, so baseline is 3; the description earns above that by teaching how to phrase `query` (a goal in the customer's own words beats a keyword list) and by explaining the effect of quoted phrases and minus-prefixed exclusions, which the schema does not. `topic`, `language`, `difficulty`, `page` and `limit` are left to 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 concrete verb and resource ("Finds seminars in the IT-Schulungen.com catalogue") and explicitly positions itself as the entry point when a topic is known but the identifier is not, which cleanly separates it from seminar_get and seminar_dates.

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 "use this first" routing rule, plus named downstream alternatives: call seminar_get with a guid for agenda and prerequisites, seminar_dates for scheduled dates. It also states when to use the quote/minus operators (only to correct a search that went wide), which is when-to-use guidance at the operator level.

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, non-destructive, open-world behavior, so the bar is lower. The description still adds real substance beyond them: alias matching ("K8s" → "Kubernetes") and the crucial semantic that a hit proves vocabulary existence, not seminar existence. It omits that the same lookup spans non-topic vocabularies (manufacturer, audience, software_version), which is a noticeable blind spot.

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 tight paragraphs: purpose first, usage second, the disambiguating caveat last. Every sentence carries information — the alias examples and the filter-axis-versus-catalogue distinction both do real work.

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?

An output schema exists so return values need no explanation, and the annotations cover the safety profile. What an agent needs to call it correctly is essentially present; the only gap is that the `type` parameter's broader vocabularies are never mentioned, which slightly undercuts the 'topic vocabulary' framing.

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 earns a point above that by documenting matching semantics the schema does not: the `query` value is matched against aliases as well as names, and the result is meant to be reused as a filter value. It says nothing about the `type` facet values, leaving that entirely to 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?

Opens with a specific verb+resource: searches the topic vocabulary seminars are tagged with. It immediately frames the tool as a lookup that feeds `seminars_search`, which distinguishes it from that sibling without the agent needing to open 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 explicit when-to-use (turn a customer's wording into a filter value, check whether a product/technology is covered) and an explicit when-not ("a hit means the topic exists, not that a seminar on it does. `seminars_search` answers that"). The alternative is named and the condition that selects it is stated.

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