disdex: Discord server search

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered; the description goes further by disclosing the four possible status outcomes (live/dead/pending/unknown) and that dead invites still resolve to a server, which is non-obvious behavior. It does not mention rate limits or how stale the 'last saw' data can be.

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?

Single dense sentence that front-loads the action and the input formats before the return semantics. It is somewhat clause-heavy with three comma-stacked ideas, but no sentence 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?

With no output schema, the description carries the burden of explaining returns and does so by naming all four status values and the associated server data. Minor gap: nothing about invalid/unknown-format input handling or response shape.

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 param is already documented, so the baseline is 3; the description adds concrete accepted syntax (discord.gg/abc, discord.com/invite/abc, bare code) that meaningfully clarifies what strings are valid. No error behavior for malformed codes is described.

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 ('look up a Discord invite link or code') and enumerates the three accepted input forms, which immediately distinguishes it from get_server/search_servers lookups. An agent can tell this checks a known invite rather than discovering servers.

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 implies usage by spelling out accepted input formats and what the result means, but it never states when to prefer this over get_server or search_servers, nor any exclusion case. The when-to-use signal is left to be inferred from the sibling names.

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, openWorldHint and destructiveHint=false, so safety is covered. The description earns credit by disclosing the concrete return content, including the 30-day member-count trend, which is behavioral detail the annotations cannot convey; it stops short of stating behavior for unknown ids or rate limits.

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

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

One front-loaded sentence that leads with the scope ('Full details for one Discord server') and then lists fields. No filler, nothing repeated from the 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?

With no output schema, the field enumeration does the work of describing return values, which is the most important gap to close for a read tool. Remaining omissions (error behavior on an invalid or deleted guild id, whether the 30-day history can be absent) are minor but real.

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 is fully documented, including the id format and its provenance from search_servers. The description adds no parameter-level meaning beyond that, so the baseline of 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 (full details for one Discord server) and enumerates the exact payload fields, so the agent knows precisely what comes back. It does not differentiate from siblings like get_server_activity or get_stats, whose outputs partly overlap with the member-count history mentioned here.

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?

No when-to-use, when-not-to-use, or alternative routing is given. Nothing says to prefer get_server over get_server_activity or get_stats, or that search_servers is the way to obtain the id (that hint lives only in the schema, not the 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 readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds genuinely useful non-schema context: values are daily averages derived from disdex's scans rather than exact snapshots, which tells the agent not to expect precise point-in-time counts. It omits day-boundary/timezone handling and data availability for untracked servers.

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

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

Two sentences, front-loaded with what is returned and scoped by time, followed by the data-quality caveat and usage examples. No filler or restatement 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?

For a two-parameter read tool with no output schema, the description conveys the returned measure (daily member and online counts) and its derived nature, which is enough to call it correctly. It stops short of describing the per-day record shape or behavior for servers with no scan history.

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%: server_id is documented and cross-references search_servers, while range has an enum and default but no prose. The description only gestures at the range parameter with "over a time window" and adds the resolution ("daily"), which is mild compensation rather than real semantics for the window choices.

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 concrete resource (one Discord server) and concrete metrics (daily member and online counts) over a time window, so the agent knows exactly what comes back. It implicitly separates itself from get_stats and get_server by scoping to a single server's historical member counts, but never names those siblings explicitly.

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 example questions ("is this server growing?", "how big was it in March?") give clear situational triggers for selection. There is no statement of when NOT to use it, and no mention of check_invite, get_server, or get_stats as alternatives for overlapping 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, openWorldHint and destructiveHint=false, so safety is covered. The description adds information the annotations cannot: the metric set returned and, importantly, that each total carries a last-refreshed timestamp, which tells the agent the data has freshness semantics. It does not describe response shape or formatting, keeping it at 4.

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 sentence with no filler that front-loads the returned metrics and then the refresh timestamps. Every clause earns its place; there is nothing to trim.

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 carries the burden of explaining return values, and it does so by enumerating the five count categories plus the last-refreshed timestamps. What remains underspecified is the response structure (flat numbers vs. an object keyed by entity, timestamp format), which would be needed for full confidence.

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 semantics to compensate for. The description correctly implies a no-argument call by describing only the returned totals.

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 the exact resource (disdex index counts) and enumerates the specific entities covered: servers, users, bots, games, invites, plus refresh timestamps. It is clearly distinct from every sibling (check_invite, get_server, get_server_activity, search_servers), none of which return aggregate counts. It only lacks an explicit verb phrase like "Returns the index totals," which is why it stops short of 5.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for index-size/freshness figures, but the description never says when to call it or when not to. Because no sibling overlaps in function (all others are per-entity lookups), the risk of misselection is low, but no explicit routing guidance is provided.

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 a safe, idempotent read, so the description's job is to add context beyond that, and it does: relevance ranking order, the partial_match fallback for longer queries, and a hard guarantee that NSFW servers are never returned. It even lists the fields of each result including the conditional joinable invite link.

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: purpose, matching fields, ranking rules, return contents, partial-match fallback, NSFW exclusion. The most important scoping facts (what is searched, how results are ordered, what is filtered out) are front-loaded.

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 takes on the burden and covers result contents (member/online counts, language, invite link). Combined with the fallback and NSFW behavior, an agent has everything needed to call and interpret this 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 71%, and the description supplements it by explaining the sort default ('relevance with a query and members without one') and the concept of browsing without a query. The tag, language, and growing_within_days parameters carry their own schema descriptions, so this is solid without being exhaustive.

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 ('Search public Discord servers indexed by disdex') and enumerates exactly which fields are matched (name, vanity URL, description, traits, guild tag). This is detailed enough that an agent can distinguish it from lookup siblings like get_server 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 concrete usage conditions: provide a query for relevance-ranked matching, omit it to 'browse everything by the chosen sort', and the schema-side descriptions cover the filters. It does not explicitly contrast with the sibling tools, so an agent must infer that check_invite/get_server are lookups rather than discovery.

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