similarity-search-api-sdk

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

Annotations are absent, so the description carries the full burden of behavioral disclosure. It reveals the key limitation that the underlying logic only exposes mean marginal entropy and not individual H(X_d) values, emphasizes that it returns a single aggregate value, and discloses that it requires an x402 payment. It could add response-shape or failure-mode details, but the core caveats are honestly and usefully disclosed.

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: it states what it does, why it is useful, what it returns, its important limitation, and its payment requirement within three sentences. The per-dimension warning is repeated once across the neutral second sentence and imperative third sentence, which adds mild redundancy but reinforces an important boundary.

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 that there is no output schema and no annotations, the description covers the essential contextual bases for an agent: what is computed, when to use it, what will and will not be returned, what the caller should not expect, and the payment requirement. The output is simple enough that saying it returns a single aggregate corpus_entropy value makes the tool's behavior sufficiently transparent.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description does not add parameter-specific meaning, but it also does not need to because the schema already provides semantic guidance such as the n_bins consistency with rank_items_by_nmi_cosine_fusion.

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, meaningful verb-resource combination: it computes the aggregate entropy-calibrated alpha for a corpus, and it explicitly says this is done without running a full search. It also differentiates itself from the sibling by stating it is NOT a per-dimension breakdown, so an agent can distinguish this from rank_items_by_nmi_cosine_fusion without opening associated schemas.

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 states exactly when to use this tool: before committing to a large rank_items_by_nmi_cosine_fusion call. It also gives a clear when-not-to-use condition: do not use it when per-dimension entropy granularity is required. This provides strong routing guidance relative to the primary sibling.

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 no annotations provided, the description carries the full burden and largely delivers: it discloses the x402 payment requirement, the stateless corpus assumption, the 0-indexed position-based result identification (no item IDs), and alpha auto-calibration from marginal entropy. The main gap is that it does not describe the shape of the returned objects despite having no output schema.

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 about five sentences long, organized as purpose, result-identification caveat, when-to-use, when-not-to-use, and payment requirement. Everything earns its place and the core action is front-loaded; only marginal trimming would be possible without losing a meaningful constraint.

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 tool of this complexity with no output schema, the agent is left without a clear contract for the returned objects — 'Results are identified by their 0-indexed position' is suggestive but does not say whether the response includes scores, ordering metadata, or just positions. Dimensionality-mismatch behavior is also unstated. Corpus size cap, defaults, payment, and ID semantics are all handled 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 100%, so the schema already documents every parameter's bounds, defaults, and meaning. The description adds some useful connective tissue — the fusion formula explains why alpha_override and n_bins exist — but it does not materially expand the semantic content of the individual parameters beyond what the schema states.

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 opening sentence names a specific verb and resource — 'Ranks a corpus of items against a query vector' — and pins down the exact scoring formula (alpha * cosine + (1-alpha) * NMI_normalizado). This makes it unambiguously distinct from its siblings, one of which estimates corpus entropy and the other scores a single pair.

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 when-to-use guidance ('Use this when you need semantically-calibrated similarity over a stateless corpus of up to 500k items without a vector database') and explicit when-not-to-use guidance ('Do NOT use for purely geometric nearest-neighbor search... nor for corpora larger than 500k items'). It stops just short of a 5 because it never names the alternative sibling tools directly, so the agent must infer which sibling covers pairwise scoring or geometric search.

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?

No annotations are provided, so the description carries the full burden. It adds important behavioral context: exactly one pair, fixed alpha, no auto-calibration, and an x402 payment requirement. It does not state the response format or whether repeated calls are expensive/cached, but the key operational traits are disclosed.

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 dense but well-organized: what it does, when to use it, important behavioral caveats, when NOT to use it, and the payment requirement. Every sentence contributes useful information, and the most important scope limitation 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 non-annotated, no-output-schema tool, the description covers selection context, invocation semantics, and cost/auth requirements well. The main gap is the exact form of the return value, but the phrase 'computes the NMI-cosine fusion score' gives sufficient high-level output understanding for most agent workflows.

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 covers 100% of the parameters with meaningful descriptions. The description reinforces the alpha/n_bins behavior but largely repeats what the schema already says, such as 'applied as-is -- not auto-calibrated' and the default value 0.5. There is no significant new parameter-level meaning beyond 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 opens with a specific verb and resource: it computes the NMI-cosine fusion score for exactly one (query, target) vector pair at a fixed alpha. It also distinguishes itself from the sibling corpus-level ranking tool by explicitly targeting explainability, debugging, and unit-level validation.

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 explicit when-to-use guidance, explicitly says when NOT to use it ('Do NOT use in a loop'), and names the batch alternative: rank_items_by_nmi_cosine_fusion. It also clarifies that alpha is not auto-calibrated for a single pair, which is a key condition for correct use.

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