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 readOnlyHint, idempotentHint, and openWorldHint, so safety behavior is covered. The description adds meaningful context beyond annotations: it lists the returned agreement statistics and explains that min_raters overrides the ranking's configured value and that api_key handling differs by endpoint. It does not contradict 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 front-loads the returned metrics, which is the most important information. The remaining sentences about min_raters and api_key are useful; the 'Layer 4' phrase is mildly contextual but not wasteful. Structure is functional despite a mid-sentence line break.

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 detailed return-value explanations are not strictly necessary, yet the description still names the returned statistics. Annotations cover the safety profile, and the description adds auth and override behavior. The only notable gap is lack of explanation for the required ranking_id parameter.

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 explains min_raters as an override and clarifies api_key behavior across endpoints, but it does not explain the required ranking_id parameter's expected format or role. Coverage is partial rather than complete.

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 resource and outcome: inter-annotator agreement metrics for a ranking, including Cohen's κ, Fleiss' κ, Krippendorff's α, Scott's π, and a coverage report. It is clear what the tool returns and is distinguishable from sibling metric tools like get_ceiling or get_crowd_bt, though it does not explicitly name those alternatives.

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 context is implied by the metric list and by notes about min_raters overriding the ranking configuration and api_key being optional on the public endpoint but required on /mcp/mcp. However, it does not say when to use this agreement tool versus other ranking-analysis siblings, nor does it provide explicit exclusions.

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 establish read-only/idempotent/open-world behavior, and the description adds substantial non-obvious context: Bradley-Terry ratings, 95% intervals, tie-aware rank semantics, the provisional flag, the method field, and the endpoint-specific api_key requirement. This is rich behavioral disclosure beyond structured fields.

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

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

Purpose is front-loaded in the first sentence, followed by compact paragraphs on return semantics and auth. It is somewhat longer than minimal but each sentence contributes useful context, with no major repetition.

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-field details need not be fully repeated, and the description still adds key semantics around uncertainty, rank ties, provisional results, and method. The remaining gaps are parameter details for limit/ranking_id and sibling routing, so it is strong but not fully 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?

With 0% schema description coverage, the description must carry parameter meaning. It explains api_key behavior (optional on the public endpoint, refused on /mcp/mcp) and maps 'top N' to limit, but gives no default or maximum for limit and no format for ranking_id.

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 ('Get') and resource ('top N entities of a ranking') plus the differentiator 'honest uncertainty,' so an agent knows what it returns. It does not explicitly contrast with siblings like aimrank_get_ranking or aimrank_get_crowd_bt, so it is clear but not fully sibling-differentiated.

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 stating it returns top N entities from a ranking, and it notes the api_key requirement on /mcp/mcp. However, it never says when to choose this over sibling ranking tools such as aimrank_get_ranking or aimrank_get_crowd_bt, so routing is left implicit.

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 discloses genuinely useful behavior beyond the schema: left/right order is randomised, match_quality measures closeness only and is not a predicted winner, and api_key is optional on the public endpoint but refused on /mcp/mcp. However, 'next pair' plus randomised ordering implies state progression and non-identical repeat results, which sits uneasily with the declared idempotentHint=true.

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 purpose is front-loaded in one line, followed by a compact strategy list and two short behavioral notes. The strategy enumeration is long but each value carries selection information; no sentence is filler.

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

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

With an output schema present, the description needn't explain return values, and annotations cover the safety profile. What remains necessary for correct invocation — strategy choice, auth requirement per endpoint, and how to present the pair — is all covered; only ranking_id's semantics and the relationship to aimrank_get_daily_pair are 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 0%, so the description has to compensate, and it largely does: it lists all seven strategy values with the default (adaptive), and explains api_key's conditional requirement across the public endpoint versus /mcp/mcp. Only ranking_id is left unexplained, though its role is inferable from the tool 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?

States a specific verb and resource: 'Get the next pair of entities to evaluate.' It also implicitly separates itself from aimrank_predict_matchup_winner by noting the pair arrives with 'no rating or predicted winner'. It doesn't explicitly name aimrank_get_daily_pair as the alternative for a scheduled pair, so sibling differentiation is only partial.

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 operational guidance for the result ('show it to the voter as-is') and enumerates the available strategies with a stated default, which is useful context. However, it never says when to choose this tool over aimrank_get_daily_pair or aimrank_predict_matchup_winner, and no exclusion criteria are given.

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 cover read-only/idempotent/open-world, but the description adds real context: a hard cap of 25 entities returned, Bradley-Terry ratings with ci_95 intervals, tie-aware shared ranks, and the endpoint-dependent api_key requirement. It does not say whether a ranking can have more than 25 entities or how to retrieve the rest, which is the main remaining behavioral gap.

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

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

Three short sentences, front-loaded with the primary action and scope, then the return semantics, then the auth caveat. No filler. The line breaks are slightly choppy but the content is 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?

With an output schema present, the description need only supply what the schema can't: the 25-entity truncation, the rating model behind the values, tie handling, and auth behavior. It covers those. What is missing is the truncation follow-up path (does a ranking exceed 25 entities, and what tool continues the list).

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 carry the load. It explains api_key meaningfully (optional publicly, required via /mcp/mcp), but ranking_id is left as a bare identifier with no format or sourcing guidance. Half the parameters get real semantics, hence a mid score.

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?

A specific verb and resource: fetch a ranking's metadata plus its top 25 entities. The 'top 25' scope and the rating/ranking semantics distinguish it from sibling list/detail tools such as get_leaderboard or list_domain_entities. It stops short of naming a sibling to route away from, so it is clear but not maximally differentiated.

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 by the required ranking_id and the note that api_key is optional on the public endpoint but refused on /mcp/mcp, which is genuinely useful auth guidance. However, there is no statement of when to choose this over get_leaderboard, explain, or discover_public_rankings, and no exclusions.

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?

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing the auth rule (api_key optional on the public endpoint, refused on /mcp/mcp), restating that no vote is recorded, and warning that pre-vote disclosure corrupts preference independence. That is real operational and integrity context an agent could not infer from structured fields.

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

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

What it does is front-loaded in the first clause, and the safety warning follows the method note in a sensible order. Five short sentences with little fat, though the 'read-only' restatement is slightly redundant with 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?

An output schema exists, so return values need no prose, and the auth and integrity caveats are covered. The remaining shortfall is the undefined boundary against `aimrank_predict` and the bare parameter names for a 0%-coverage schema.

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

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

Schema description coverage is 0%, so the description carries the burden; it does explain `api_key` semantics in detail (optional vs. required per endpoint), but `ranking_id`, `entity_a_id` and `entity_b_id` are left entirely undocumented beyond their names. Partial compensation for a full-coverage 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 verb and resource ('Predict a matchup's winner from the current ratings') and even names the underlying method (Glicko-2 win probability). It does not, however, distinguish itself from the sibling tool `aimrank_predict`, which an agent could plausibly confuse it with.

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?

Clear contextual guidance: use it to analyse a ranking, or after a vote to compare the recorded vote against expectation, and explicitly never show the prediction to a voter beforehand, with the reason given. The one gap is that it never names a sibling alternative (e.g. `aimrank_predict`) or says when to prefer that instead.

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.