AimRank

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

The description adds useful behavior beyond annotations: it reveals that this is a URL-generation tool rather than a mutating 'create' operation, that OG images render automatically on unfurl, and that api_key handling differs between public endpoints and /mcp/mcp. The annotations already mark readOnly and idempotent, and the description is consistent with 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?

The description is compact and front-loaded: the first sentence gives the core purpose, the second lists formats, and the third handles api_key nuance. Every line earns its place without redundancy or filler.

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

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

The description covers the main behavioral and usage aspects, and the output schema can explain return values. It leaves some ambiguity around how an agent should obtain the api_key when calling via /mcp/mcp, but otherwise the description is complete enough for correct invocation.

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

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

Schema coverage is 0%, but the description compensates by enumerating valid format values and explaining api_key optionality/requirements per endpoint. ranking_id is not described, but its role is self-evident from the tool name and required status.

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 action and resource: 'Return share-ready URLs + embed snippets for a ranking.' It also lists concrete output formats, making the purpose clear. It does not explicitly differentiate from sibling tools like aimrank_get_data_card, but the focus on share/embed artifacts distinguishes it sufficiently.

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

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

The description gives clear context: the output is meant to be pasted into tweets, blogs, Notion pages, or Slack messages. It does not explicitly say when not to use this tool or point to alternatives, but the usage scenario is well implied.

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, openWorldHint, and idempotentHint. The description adds valuable behavioral context beyond that: api_key optionality and refusal on /mcp/mcp, plus the embedding of share assets so results can be handed as clickable links. No contradictions.

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

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

The description is compact yet dense: a clear purpose, a terse list of filter constraints with enums, a practical note about share assets, and an auth caveat. Every sentence carries useful information 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?

Given the output schema exists (handling return values) and annotations cover open-world/read-only/idempotent behavior, the description is fairly complete. It addresses authentication, parameter domains, and result embeddability. The only gap is that 'category' values are not enumerated, but for an open-world browsing tool this may be intentional.

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 must compensate. It lists the filters category, media_type with explicit allowed values, sort with explicit values, limit range 1-50, and notes api_key optionality. It does not detail category values, which remain open-ended, but overall it provides substantial semantic meaning beyond the bare 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 clearly states the verb 'browse' and the resource 'public rankings', with the analogy 'surfing aimrank.io' that conveys discovery. It distinguishes from sibling tools like get_ranking/get_leaderboard by framing this as a public browsing/discovery tool, not a targeted fetch.

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 a browsing/discovery use case ('surfing aimrank.io') with filters, but it does not explicitly state when to prefer this tool over siblings or when not to use it. It provides context about the public endpoint and auth quirks, but no exclusionary 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?

The annotations already provide readOnlyHint, openWorldHint, and idempotentHint, which cover non-mutating and idempotent behavior. The description adds valuable context beyond annotations: it clarifies that the output is deterministic (not LLM-generated), includes specific Glicko-2 inputs (μ/φ), and tailors to Annex IV audit needs. It also discloses API key behavior differences between endpoints (public vs /mcp/mcp), which is behavioral transparency beyond annotations. This adds significant context about stability and authentication nuances.

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

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

The description is compact, three short paragraphs, with front-loaded purpose. The first sentence immediately states the tool's purpose and contract. The second paragraph explains the output and use case, and the third gives a crucial API key nuance. Every sentence adds value: no fluff, no repetition of schema details. The structure is clear and efficient.

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?

The tool has an output schema, so the description needn't detail return values. The description covers purpose, behavioral traits (deterministic, non-LLM), and even authentication nuances (api_key). It mentions the target audience (Annex IV auditor) which aids in usage context. The only gap is that it doesn't explain what the narrative might contain or how to interpret the μ/φ inputs, but since the output schema likely covers that, it is relatively complete. The main missing piece is explicit guidance on when to use this vs similar tools like aimrank_predict_matchup_winner, but given the strong purpose clarity and output schema, it's adequate.

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

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

The input schema has 0% description coverage, and the description does not explain any of the four parameters beyond their names. It does mention api_key is optional on the public endpoint, which adds some semantic insight into that parameter. However, for ranking_id, entity_a_id, entity_b_id, the description provides no meaning beyond what the schema provides (just field names). Given the schema is minimal and the description doesn't compensate, a score of 3 is appropriate, as it partially addresses api_key semantics but not the others.

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

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

The description clearly states that the tool explains a prediction in terms of features and narrative, specifically for the iCOMPLY contract. It mentions 'Glicko-2 μ/φ inputs' and 'deterministic narrative', which gives a clear sense of the tool's function. While the name 'aimrank_explain' suggests explanation, the description adds specificity by detailing the output nature and the absence of LLM-synthesised rationale, distinguishing it from generic explainability tools. However, it could be slightly more explicit about the context of 'prediction' (likely from aimrank_predict), but the intent is clear.

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 when to use this tool: when an auditor needs to trace the actual numbers behind a prediction via an Annex IV framework. It also contrasts with LLM-synthesised explanations, suggesting it is the alternative for deterministic, traceable output. However, it does not explicitly name sibling tools like aimrank_predict or aimrank_get_matchup that might be alternatives. The context of 'Annex IV auditor' provides a clear scenario, which is strong guidance, but lacking explicit exclusions or direct sibling comparisons.

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 mark it read-only, open-world, and idempotent; the description adds substantial beyond-annotation behavior: TF-IDF + cosine similarity, which fields are searched, no embedding API calls, 5-minute cache, public-scope restriction, score thresholds, and API-key behavior. No contradiction with annotations.

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

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

Every sentence adds information: usage modes, constraint, algorithm, caching, scope, scoring thresholds, and auth context. The most important usage rule (exactly one of query/domain_id) is 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?

Covers algorithm, data scope, auth, caching, and score interpretation. The only notable gap is return-value shape/ordering of results, which matters because no output schema is provided. Still highly actionable overall.

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 has 0% description coverage, so the description carries the burden. It explains query vs domain_id semantics, the exclusivity constraint, and api_key behavior. Limit is left to its self-evident name/defaultaiman, and the score-threshold guidance isn't tied explicitly to a parameter, but overall compensation is strong.

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+object ('Find public domains most similar to...') and immediately clarifies the two input modes (query vs domain_id). The purpose is unambiguous and does not overlap confusingly with sibling tools.

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?

Clearly instructs when to use query vs domain_id, states that exactly one is required, and notes the public-endpoint versus /mcp/mcp auth difference. It does not explicitly name sibling alternatives, but the selection logic is explicit and actionable.

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 the tool read-only and idempotent, so the bar for additional behavioral disclosure is lower. The description adds meaningful context: `min_raters` overrides the ranking's configured value, and `api_key` behaves differently on the public endpoint vs `/mcp/mcp`. This goes beyond what annotations and schema provide.

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

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

The description is compact and front-loaded: the first line states the purpose and output, followed by two short parameter clarifications. The unexplained phrase 'Layer 5' is mildly cryptic and prevents a perfect score, but it is not wasteful.

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, idempotent metrics tool with an output schema and one required parameter, the description is largely complete. It covers the core return value, the auth nuance, and the override behavior. It is missing only explicit guidance on which scenarios make agreement calculation meaningful, but that is not critical for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does so for two of three parameters: `min_raters` is explained as an override, and `api_key` is clarified with endpoint-specific behavior. `ranking_id` is left implicit, but its role is recoverable from its name, required status, and the tool's stated purpose.

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 resource (inter-annotator agreement) and lists the exact metrics returned (Cohen's κ, Fleiss' κ, Krippendorff's α, Scott's π, plus a coverage report), making the tool's purpose unmistakable. The `ranking_id` parameter anchors it to a specific object, and the metric list distinguishes it from the many sibling `get_*` tools.

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 guidance is given about when to pick this tool over siblings such as `get_crowd_bt`, `get_ceiling`, or `get_leaderboard`. The description only explains parameter overrides and endpoint auth behavior, so the agent must infer usage from the tool name and return behavior.

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, openWorldHint, and idempotentHint. The description adds useful behavioral context beyond those hints: 'api_key is optional on the public endpoint; on /mcp/mcp a missing key is refused.' This endpoint-specific auth nuance is not carried in annotations or schema and is relevant for successful invocation.

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 three short sentences, each serving a distinct purpose: defining the metric, stating the decision-use context, and flagging endpoint-specific auth behavior. There is no filler or redundant 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?

With an output schema present and safety annotations already covering read-only/idempotent behavior, the description is mostly complete. The main gap is parameter-level semantics, particularly min_overlapping_items and the exact meaning of ranking_id. The domain-specific ceiling context and auth nuance make it close to fully self-sufficient.

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 0%, so the description must compensate for parameter documentation. It adds meaning for api_key (optional/refused context) and implies ranking_id connects to the ranking domain, but it does not explain min_overlapping_items or specify what ranking_id must reference. Coverage is too incomplete for a low-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 states the tool's purpose with a specific verb and resource: 'Pairwise-κ ceiling from qualification attempts.' It also defines the output concept as 'the upper bound any judge / RM can credibly hit on this domain,' which distinguishes it from sibling metrics like agreement or Plackett-Luce. The description is neither tautological nor vague.

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

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

The description gives concrete usage context: the result is 'used to pin the L3 pilot refund clause (refund if κ < ceiling - 5pp).' This tells an agent when the value matters. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear for selection among sibling tools.

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, and open-world hints. The description adds that it 'is not a live engine' and clarifies api_key handling on different endpoints, which are meaningful behavioral details beyond the annotations, especially regarding authentication requirements.

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 concise paragraphs: the first defines the purpose, the second notes api_key endpoint differences. No filler, and the core purpose is front-loaded. It could be slightly more structured but remains efficient.

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 having an output schema, the description omits parameter semantics, input requirements (ranking_id is required but not stated), and usage context relative to siblings. Given the statistical complexity of CrowdBT, this is insufficient for an agent to invoke the tool correctly without additional investigation.

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 0%, and the description offers no explanation of ranking_id, max_iterations, min_votes_per_entity, or min_votes_per_annotator. It only mentions the model concept ('entity scores', 'reliability η'), leaving agents without any guidance on how to set these parameters correctly.

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

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

States it performs a 'joint fit of entity scores + per-annotator reliability η' and explicitly identifies itself as a 'methodology audit, not a live engine.' This clearly defines the tool's scope and distinguishes it from live-ranking siblings like get_leaderboard, though it doesn't name any sibling 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?

Provides context that it's for auditing methodology rather than live use, and notes api_key behavior per endpoint ('optional on the public endpoint; on /mcp/mcp a missing key is refused'). However, it doesn't specify when to choose this over related tools like aimrank_get_agreement or aimrank_get_plackett_luce, leaving the routing 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, openWorldHint, idempotentHint. The description adds crucial behavioral details beyond these: the fallback mechanism with ok=False and the api_key requirement difference between public and /mcp/mcp endpoints. This is valuable context an agent needs to interpret responses correctly.

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 main purpose, and every sentence earns its place. No redundancy or filler; the fallback and api_key notes are essential and efficiently phrased.

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?

Since an output schema exists, the description needn't detail return values. It covers all necessary contextual information: purpose, fallback condition, and auth requirements. Nothing an agent needs to decide and invoke correctly is missing.

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

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

Schema has a single optional `api_key` with no description (0% coverage). The description fully compensates by explaining when the key is required and when it is optional, providing precise semantics 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?

The description clearly states the verb 'Fetch', the resource 'today's Daily Pair', and differentiates it via 'trending matchup chosen at 00:00 UTC' and the 'vote_of_the_day' agent template. It explicitly names the sibling `aimrank_get_matchup` as an alternative, making the purpose 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?

The description gives explicit usage context: when to call (to get the daily pair) and when not to (if cron hasn't run, fall back via ok=False to `aimrank_get_matchup`). It also provides endpoint-specific api_key guidance, covering prerequisites.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable endpoint-specific behavioral context: api_key is optional on the public endpoint but a missing key is refused on /mcp/mcp. It also states the output format choices and the synthetic nature of the artifact, which is beyond what the annotations or schema alone provide.

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

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

The description is compact and front-loaded: the first line states the core purpose and artifact contents, the second covers output formats in a direct way, and the third covers api_key behavior. The phrase 'Layer 7' is unexplained jargon and is the only notable inefficiency; otherwise, every sentence earns its place.

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

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

Given schema, annotations, and output schema, the description covers the major operational points: artifact content, format choice, and auth. The main gap is why an agent would prefer this over per-ranking or per-agreement sibling tools, and there is no guidance on how ranking_id should be obtained. Still, for invocation-focused needs it is enough.

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 0%, so the description must compensate for all parameters. subject, however, it only explains formatting_messages: format defaults to markdown and json is available for a structured summary; api_key is optional on the public endpoint but refused on /mcp/mcp. It says nothing about ranking_id beyond its property key, so an agent must still infer the provenance and format of that 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?

The description clearly states a specific verb and resource: it produces an automatic data card containing provenance, IAA, coverage, per-annotator quality, and agreement stats as a markdown audit artifact. This is more specific than many get_* siblings, though it does not explicitly contrast the tool with any sibling, so differentiation is conveyed mainly by content rather than direct comparison.

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

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

The description gives limited operational guidance: the format options and the api_key endpoint behavior. It does not state when to choose this over alternatives like aimrank_get_ranking or aimrank_get_matches, nor does it provide exclusions or alternative-selection criteria. The intended usage must be inferred from the purpose sentence.

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 open-world behavior. The description adds valuable behavioral context beyond annotations by disclosing endpoint-dependent authentication: api_key is optional on the public endpoint but refused when missing on /mcp/mcp. This helps the agent make correct runtime decisions.

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

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

The description is compact and front-loaded with the core purpose. The second sentence adds an essential invocation nuance without waste. Every sentence earns its place.

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

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

With an output schema present, the description need not restate return values, and it provides the key endpoint-specific authentication caveat. It is slightly incomplete in not guiding tool selection among siblings, but for a simple read-only get-by-ID operation, the necessary calling context is largely covered.

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 0%, and the description does not explain domain_id beyond its self-evident name. However, it does add meaningful semantics for api_key by explaining the endpoint-specific requirement, which is not visible in the schema. This partially compensates for the lack of schema descriptions.

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 clear verb and resource: "Get domain details including entity pool and competition list." This identifies the tool's function and distinguishes it from more specific list tools like list_competitions, though it does not explicitly name a sibling or contrast behavior.

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

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

The description gives no guidance about when to use this tool versus alternatives such as aimrank_list_domain_entities or aimrank_list_competitions. The api_key note is about endpoint authentication, not tool selection, so the usage context is absent.

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 indicate read-only, idempotent, open-world behavior, and the description adds actionable auth context: api_key is optional on the public endpoint but required on /mcp/mcp. It also exposes the rating-based ordering semantics. No contradiction with annotations.

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

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

Two short sentences with the core purpose front-loaded and the auth caveat separated. Every phrase earns its place.

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

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

For a simple read-only leaderboard tool, the description plus output schema covers purpose, ordering, and auth behavior. It could name a sibling alternative or state how rankings are identified, but nothing essential is missing for a basic call.

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?

With 0% schema description coverage, the description compensates well: 'top N' communicates the limit parameter, 'of a ranking' ties to ranking_id, and the api_key sentence explains its optionality and endpoint-specific requirement. Only the default behavior of limit is 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?

The description uses a specific verb-object pair ('Get the top N entities of a ranking') and defines the sort order ('sorted by rating'), so an agent can tell it apart from sibling tools like aimrank_get_ranking. The 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?

The wording implies using this when the top-scored entities of a ranking are needed, but it never states when not to use it or names alternatives. Context is inferred from the purpose rather than explicit 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?

Annotations already signal readOnlyHint, openWorldHint, and idempotentHint, so the tool is well-characterized as a safe, side-effect-free operation. The description adds specific behavioral context: api_key is optional on public endpoint but required on /mcp/mcp, which clarifies authentication behavior. It does not detail what happens when no more pairs are left or how the strategy affects selection, but annotations lower the burden. No contradiction.

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

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

The description is compact and front-loads the core purpose. The strategy list is efficient and the api_key note is a separate, clear sentence. No redundant filler. It is appropriately sized for a simple tool with a short parameter list.

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

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

Given the presence of an output schema and annotations that indicate a safe read operation, the description covers the essential call premise: what to expect (next pair), how to choose strategy (list), and an authentication caveat. It does not explain the difference between strategies or edge cases (e.g., exhausted pairs), but this is partially mitigated by the output schema and does not block correct invocation. Adequate but with gaps for nuanced usage.

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 0%, so the description must compensate, but it only adds clarity for two parameters: 'strategy' (lists valid values) and 'api_key' (optionality conditions). The 'ranking_id' parameter is not elaborated, but its purpose is fairly self-evident from the tool name. The description adds some value beyond the schema (strategy semantics) but does not fully cover all parameters.

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

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

The description clearly states that the tool retrieves 'the next pair of entities to evaluate' for a given ranking. This verb+resource structure is explicit and distinguishes its purpose from siblings like 'get_daily_pair' and 'predict_matchup_winner'. However, it doesn't explicitly state the context of 'matchup' evaluation (e.g., pairwise comparisons) beyond the name, but the description does not conflate it with other actions.

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 lists available strategies with 'adaptive' as default, implying usage contexts for each (e.g., balanced vs random). It does not explicitly provide when-to-use vs when-not-to-use guidance or compare to alternatives. The statement about api_key requirements gives an important usage condition but not strategy selection. This is implied rather than explicit.

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, openWorldHint=true, idempotentHint=true. The description goes beyond by stating it NEVER writes ratings, reports post-hoc, and that using it as a ranking algorithm returns 400. It also discloses the api_key endpoint nuance. No contradiction with annotations; substantial added behavioral context.

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 appropriately sized with front-loaded 'OFFLINE AUDIT ONLY'. Each sentence adds value: purpose, constraints, algorithm background, and API key note. It's slightly dense but not wasteful.

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?

Covers the tool's role, safety profile, and endpoint specifics. It lacks explicit parameter documentation and clear comparison with CrowdBT, but the output schema exists, so return value is covered. For a complex algorithm tool, it's moderately complete but leaves parameter understanding to the agent.

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 0%, so the description must compensate. It only explains api_key optionality (though that's also in schema), but does not explain max_iterations or min_appearances_per_entity. The algorithm context hints at their meaning but doesn't provide explicit semantics. Given the low coverage, this is a significant gap.

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 purpose: Plackett-Luce listwise ranking aggregation, and explicitly frames it as an offline audit tool. It differentiates from siblings by noting it's one of two offline aggregators (with CrowdBT) and not a rating engine. The verb 'get' plus resource is clear.

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?

Clearly indicates when to use: as a second-opinion aggregator for audit purposes, and when not: setting it as a ranking's algorithm returns 400. It also distinguishes between public and /mcp/mcp endpoints for api_key. However, it doesn't explicitly contrast with CrowdBT or other aggregators in terms of selection criteria.

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, openWorldHint, and idempotentHint, so the description correctly avoids restating them. It adds valuable context about api_key behavior (optional on public endpoint, refused on /mcp/mcp), which is not covered by annotations and is critical for successful invocation.

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 with zero filler. The core purpose is front-loaded in the first sentence, and the second sentence adds a critical behavioral detail. Every word earns its place.

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

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

The description covers the key behavior (metadata + top 25 sorted by rating) and the api_key nuance. An output schema exists, so return values are handled there. It is complete enough for an agent to call the tool correctly, though it could mention what 'metadata' includes.

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?

With 0% schema description coverage, the description must compensate. It explains api_key's optionality and endpoint-specific behavior, which adds meaning beyond the schema. However, ranking_id is not explicitly described, though its purpose is clear from the name and the tool's purpose. The compensation is partial but adequate.

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

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

The description clearly states a specific verb (Fetch) and resource (ranking's metadata + top 25 entities sorted by rating). It precisely distinguishes this tool from siblings like aimrank_get_leaderboard or aimrank_get_ceiling by specifying the exact output scope.

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 guidance is given on when to use this tool versus alternatives. It does not mention any exclusions or conditions that would route an agent to a sibling tool, leaving the agent to infer usage from the name and purpose alone.

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, openWorldHint, and idempotentHint, which the description aligns with by calling it a probe. The description adds specific context about what is checked (liveness and DB connectivity) but does not disclose additional behavioral traits such as response format, error behavior, or potential side effects. Since annotations cover safety, this is adequate but not richly descriptive.

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

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

The description is a single sentence with zero wasted words. It front-loads the core purpose ('liveness + DB-connectivity probe') and the contract reference, making it immediately actionable. Every element contributes to understanding the tool.

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

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

For a simple health check with no parameters and an existing output schema, the description covers the essential purpose. It does not specify what happens on failure, but the output schema likely conveys return values. The description is sufficient for an agent to understand and call 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?

The tool has no parameters, so the schema is trivially complete and the description has nothing to add. According to the rubric, a zero-parameter tool gets a baseline of 4, and the description does not need to explain any parameters.

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

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

The description clearly states it is a liveness and DB-connectivity probe for the iCOMPLY contract. The verb 'probe' and the resource make the purpose clear and distinguishable from sibling tools, which are data queries and prediction operations. The term 'iCOMPLY contract' is somewhat internal but does not obscure the core function.

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 for checking service health, but provides no explicit guidance on when to use it versus alternatives. It does not mention that it is the health check among siblings, although it is unique in that role. The context of being a health check is conveyed but not fully elaborated with exclusions or 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 already declare readOnlyHint=true and idempotentHint=true UTF-8. The description adds a valuable behavioral detail: api_key is optional on the public endpoint but required on /mcp/mcp. This is beyond the structured data. It doesn't mention pagination or limits, but it's not essential here.

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, front-loaded with the action and scope, then a useful endpoint-specific auth caveat. No fluff or restatement of the 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?

Covers purpose, scope, and the only auth nuance that could trip up an agent, plus an output schema is provided. Missing deeper details about domain_id format, but the parameter is self-explanatory and required.

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 0%, so the description must add meaning. It explains the api_key auth nuance and implies domain_id selects the domain, but does not define domain_id's format or required semantics explicitly. Partial compensation.

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 clear verb ('List'), a resource ('competitions'), and the scope ('in a domain'), and explicitly includes the categories open voting and brackets. It doesn't explicitly distinguish itself from sibling list tools, but the resource is specific enough to avoid ambiguity.

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 context — listing competitions within a domain — but does not state when to choose this over sibling tools like aimrank_list_domain_entities or aimrank_get_ranking. This is adequate but not explicit 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 establish readOnlyHint and idempotentHint. The description adds real behavioral detail: results are sorted by ratingainer and the api_key requirement varies by endpoint. It stops short of stating sort direction or pagination behavior.

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, no filler. The first states the core purpose and sort order; the second adds the critical endpoint-specific authentication nuance. Every sentence earns its place.

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

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

The description, schema, and annotations together cover purpose, read-only safety, idempotency, and the api_key endpoint nuance. The output schema presumably documents results. However, it does not specify whether rating is ascending or descending, and there is no mention of pagination or list size limits.

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 schema has no description fields (0% coverage), and the description adds some context for api_key by explaining endpoint-specific optionality/refusal. However, domain_id is not explained beyond implying 'a domain's pool,' and no format or constraints are given.

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 action and scope: 'List all entities in a domain's pool sorted by rating.' This is clear and distinguishes it as a comprehensive listing operation, though it does not explicitly contrast with sibling tools.

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 guidance is given on when to use this tool versus alternatives like search or discovery tools. The phrase 'all entities' hints at a full listing, but there is no explicit when-to-use or when-not-to-use 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 declare readOnly, openWorld, and idempotent hints. The description adds important behavioral detail beyond those: returned artifacts are summaries only, full prompt text is excluded, and api_key handling differs between the public endpoint and /mcp/mcp. This meaningfully informs agent expectations without contradicting the annotations.

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

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

The description is compact and well-structured: purpose first, then filters, sort options, return behavior, and auth nuance. Every sentence adds useful information, and the critical limitation about missing full prompt text is stated prominently.

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 an output schema present, no required parameters, and annotations covering read-only/idempotent behavior, the description covers everything an agent needs to call the tool correctly: what is returned, how to filter and sort, how to get the full prompt, and the auth distinction between endpoints.

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 0%, so the description carries the burden of explaining parameters. It explains category and domain_id as filters, details sort options including the default and ordering, and clarifies api_key optionality. Only `limit` is left unexplained, but its schema default and obvious meaning reduce the gap.

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 starts with a specific verb and resource: 'Browse public judge-prompt artifacts shared by other users.' This clearly identifies what the tool does and sets it apart from sibling list/discovery tools, which target rankings, competitions, or domains rather than judge-prompt artifacts.

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

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

The description gives clear context for use: browse summaries, then call `aimrank_fork_judge_prompt` or the REST GET when the full prompt is needed. It does not explicitly state when NOT to use this tool versus every sibling, but the follow-up routing and endpoint-specific auth note provide practical usage 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?

With readOnlyHint, openWorldHint, and idempotentHint already present, the description adds useful behavior beyond annotations: the response includes provenance fields, is shaped for iCOMPLY ingestion, and api_key is optional on the public endpoint but refused on /mcp/mcp. No contradictions.

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 crisp sentences: purpose and output shape, integration contract pointer, and auth behavior. Each sentence earns its place and the most important scoping information is 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?

For a read-only, idempotent prediction tool with an output schema, the description covers the essential call context: what it returns, who consumes it, and how api_key behaves per endpoint. The main omission is fuller parameter semantics, but schema structure and the contract reference keep this adequate.

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 0%, so the description has to compensate. It adds meaning for api_key (endpoint-dependent requirement) and contextually defines entity_a_id/entity_b_id by calling this a pairwise prediction. However, it does not explain ranking_id or provide any value/format constraints, leaving a material gap in parameter semantics.

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

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

The description clearly states a specific verb and resource: it returns the engine's predicted winner plus probability, and scopes it to the iCOMPLY contract with provenance fields. It does not explicitly contrast itself with the closely named sibling aimrank_predict_matchup_winner, so differentiation is implied by the iCOMPLY-specific output shape rather than stated.

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 clear context for when to use the tool: when the response must feed iCOMPLY's Annex IV section-4 generator, and it points to the integration contract document. It does not mention when not to use it or name alternatives, so it stops short of the 5-level 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?

The description goes beyond the readOnlyHint annotation by explicitly stating 'Does not record a vote' and clarifying the internal Glicko-2 formula. It also explains the api_key requirement differences between public endpoint and /mcp/mcp, which is behavioral context an agent needs. No contradiction with annotations.

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

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

Purpose in first sentence, then formula and workflow pairing, then auth note. No filler, each sentence carries distinct useful info.

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?

The description covers purpose, formula, workflow pairing, read-only behaviorhoed, and endpoint-specific auth. It doesn't mention output shape/return value, but the presence of an output schema partially mitigates that. For a prediction tool, the description covers the core decision context well.

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 0%; the tool description only explains api_key behavior. ranking_id, entity_a_id, and entity_b_id are not semantically defined beyond their names, leaving an agent to infer they refer to the ranking and two entities to compare. Since schema carries no descriptions stolen, this lack of elaboration leaves gaps.

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 clear action ('predict') and object ('matchup winner') with the specific timing condition 'before a vote.' It also distinguishes itself from vote-recording tools by explicitly saying 'Does not record a vote — read-only.' The sibling aimrank_submit_vote and aimrank_get_matchup are implicitly distinguished by this purpose.

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 clearly frames the tool as the prediction half of the 'Claude predicts, you vote, we compare' workflow and states the pairing with aimrank_submit_vote. It also gives endpoint-specific guidance about the api_key. It does not explicitly contrast itself with sibling prediction/retrieval tools like aimrank_get_matchup, but enough context is given for an agent to choose it for the intended flow.

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 openWorldHint=true, so the safety profile is covered. The description adds the api_key requirement nuance (optional on public, required on /mcp/mcp), which is real behavioral context beyond annotations. But it doesn't describe pagination, result ordering, or behavior when no matches are found.

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 concise sentences deliver the core purpose and an important edge case about auth. No fluff. Slightly terse given the behavioral constraints, but overall efficient and 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?

The search tool has 4 params, 0% schema coverage, and an output schema present. The description covers the main action and the api_key nuance but doesn't clarify query semantics or ranking_id meaning. Given the output schema exists and annotations cover safety, this is adequate but not complete.

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 0%, so the description carries some burden to explain parameters. The description clarifies the api_key parameter's conditional necessity, which compensates slightly. But it doesn't explain limit semantics, query behavior, or ranking_id beyond what the schema provides. The api_key note is the only value-add over the schema.

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

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

Description states a specific verb ('find') and resource ('entities by name substring within a ranking'), which clearly identifies what the tool does. It doesn't explicitly distinguish from siblings like aimrank_list_domain_entities, but the 'substring search within a ranking' framing is enough to differentiate it from pure listing tools.

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

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

The description gives an implementation detail about api_key on the public endpoint vs /mcp/mcp, but doesn't say when to prefer this tool over siblings like list_domain_entities or discover_public_rankings. No guidance about when to use search vs list, or what contexts warrant a substring query versus an exact lookup.

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