capalens

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world. The description adds real behavioral boundaries beyond that: unknowns/permission/cost gaps 'remain blockers', the tool performs 'no entity resolution, provider execution, credential handling or safety certification', and sources/user text are untrusted data. That is genuine scope-limiting context an agent needs, though it does not describe pagination or return 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?

The purpose and the compact/detail distinction are front-loaded, which is good. But the trailing sentence about the 'original seven catalog tools' retaining existing behavior earns little for an agent trying to call this tool, and the boundary list reads as a dense run-on. Efficient in parts, padded in others.

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 12-parameter tool with deeply nested objects and no output schema, the description covers purpose, default detail mode and scope limits. It does not explain the snapshot/selection pinning protocol or how evidenceContext is supplied, which the schema hints at but does not fully narrate. Adequate but with visible gaps.

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 58%, and the schema itself documents pathId, limit, at, language, snapshotSha256 and selectionSha256. The description adds meaning for the detail enum (naming the readable page types) and the compact-without-pagination rule, but leaves offset, selectedBranchIds, evidenceContext and the large brief object unexplained. Partial compensation for a mid-level 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+resource: 'Read a conservative assessment of one recorded work path against a need brief.' This is clearly distinguishable from the candidate_* catalog siblings, which operate on software records rather than work-path assessments. It stops short of naming any sibling, so it does not reach the sibling-differentiation bar for a 5.

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

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

'Compact is the default' plus the enumeration of detail pages (steps, fields, candidates, handoffs, evidence) implies when to request more detail. However there is no explicit when-not or comparison against any alternative tool, and the closing note about 'original seven catalog tools' is too vague to route an agent. Usage context is implied rather than stated.

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, closed-world, non-destructive behavior, and the description genuinely adds value on top: it enumerates what is NOT produced (scores, cost totals, suitability conclusions, vendor calls) and discloses that documentation is not reviewed and vendor integrations are untested. That is meaningful negative-scope context beyond 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 core comparison statement is front-loaded and the exclusion list is useful, but the later sentences ('Complete declarations appear once in interfaces...') are opaque jargon that do not clearly earn their place and slightly dilute an otherwise tight description.

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

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

With no output schema, the description carries extra burden, and it does usefully state what is not returned. But the actual returned content ('recorded gaps') is left vague and the parameter behavior is largely unaddressed, so it is only adequate for a 5-parameter comparison tool.

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

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

Schema description coverage is only 60%, and the description adds almost no meaning to the parameters. Lines like 'Complete declarations appear once in interfaces; matched/guide entries are explicit local references' are cryptic and do not map visibly onto fields, pricing, locale, or language, leaving part of the gap uncompensated.

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: 'Compare 2 to 4 exact selected candidate IDs and their recorded gaps', with a clear cardinality bound. It implies the 'selected candidate' scope that distinguishes it from the sibling compare_software, but never names that sibling or explicitly contrasts the two, so an agent must infer the boundary.

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?

'Only the retained current observation is available; historical batch queries are not accepted' gives a partial when-not condition. However, no alternative tool is named and no positive guidance on when this is preferred over compare_software or candidate_get_software is given, so usage is only 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 establish read-only, idempotent, non-destructive behavior, while the description adds important constraints: no install/authenticate/execute/runtime compatibility, documentation unreviewed, vendor integrations untested, and only the retained current observation available. These are useful behavioral disclosures with no contradiction, though the sentence about 'complete declarations' is opaque.

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 main operation, but the sentence 'Complete declarations appear once in interfaces; matched/guide entries are explicit local references' is cryptic and does not clearly help invocation. Overall size is appropriate, but not 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?

No output schema exists, yet the description does not explain the structure or contents of the returned declaration or checklist. For a 6-parameter tool with several enums and no output schema, this leaves key invocation and interpretation gaps despite useful limitation notes.

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 67%, with descriptions for id, locale, language, and includeChecklist. The description only indirectly hints at includeChecklist via 'manual review checklist' and the retained-observation constraint, and says nothing about type, pricing, locale, or language parameters, so it adds limited 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?

States a specific read operation on one selected candidate declaration and manual review checklist. Clear enough to identify the resource, but it does not explicitly connect 'integration guide' to the tool name or distinguish the tool from sibling get_integration_guide or candidate_get_review_summary.

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

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

Gives exclusions such as 'historical batch queries are not accepted' and non-actions, but no explicit when-to-use guidance or alternative-tool routing. The agent must infer applicability from the purpose sentence and tool name rather than from stated conditions.

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?

Beyond the read-only and idempotent annotations, the description discloses important behavior: the result is not-collected with null statistics, documentation is not reviewed, vendor integrations are untested, only retained current observations are available, and historical batch queries are rejected. These are substantive behavioral limitations that an agent would not know from annotations alone.

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 front-loads the key result behavior in the first two sentences, but later sentences are dense and somewhat cryptic. Phrases like 'matched/guide entries are explicit local references' add ambiguity rather than cleanly supporting tool selection.

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?

There is no output schema, so the description must explain return behavior; it does so by stating that the result is not-collected with null statistics. It also covers key limitations and safety context, though it remains somewhat unclear about how interfaceId and capability interact with the candidate-set behavior.

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 80%, so most parameter meaning is already documented in the input schema. The description adds little about individual parameters such as softwareId, interfaceId, capability, language, or locale, beyond implying that historical batch queries are unavailable.

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 that this candidate review-summary tool returns not-collected with null statistics because the selected candidate set has no human review evidence. It also distinguishes the result from a zero rating or a formal catalog review summary. The purpose is clear despite awkward phrasing.

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 implies the tool is only for the selected candidate set and that historical batch queries are not accepted, which helps constrain usage. However, it does not explicitly point to the sibling get_review_summary or clearly state when an agent should choose this tool instead of 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 readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description adds substantial context: no reviewed vendor identity or canonical join, no verified price, documentation unreviewed, vendor integrations untested, and only the retained current observation is available. That is genuinely useful limitation disclosure beyond the annotations, though the phrasing is occasionally opaque.

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

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

The core action is front-loaded correctly and the passage is not bloated, but several sentences are cryptic jargon ("Complete declarations appear once in interfaces; matched/guide entries are explicit local references") that an agent cannot easily act on, weakening value density.

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 9-parameter tool with a conditional schema and no output schema, the description covers input rejection and several contract limitations but never characterizes the response content, which it must do in the absence of an output schema. Adequate but with a clear gap on return-value expectations.

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 67%, above the midpoint, and the schema itself already documents id, locale, language, pricingPart, pricingOffset and pricingSnapshotSha256. The description reinforces the id rejection rule and the current-observation-only/paging constraint but says nothing about fields, pricing, or interfaceId, leaving part of the 9-param contract unaddressed. Baseline 3 fits.

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 gives a concrete verb and resource ("Read one exact selected candidate ID"), which is better than a tautology. However, the remaining sentences are dense caveats that obscure what is actually returned, and the description never distinguishes this candidate-lane tool from its plain sibling get_software. An agent can guess the purpose but not cleanly separate it from the near-identical sibling.

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 provides real when-not guidance by listing rejected inputs (upstream names, aliases, outside-selection IDs, historical ID aliases) and stating historical batch queries are not accepted. But it never names an alternative tool (e.g. candidate_search_software for finding IDs), so routing guidance is only 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, idempotentHint, destructiveHint=false and openWorldHint=false, and the description is consistent with them ('Reading candidate metadata does not write statistics'). It adds genuinely non-schema context (fixed observed output shape, no documentation review, untested vendor integrations, no historical/batch queries), but the sentences are cryptic and the 'not-collected with null counts' claim is never reconciled with the tool's apparent reporting purpose.

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

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

Six dense, jargon-laden sentences ('Complete declarations appear once in interfaces; matched/guide entries are explicit local references') that are not front-loaded and bury any actionable meaning. Space is spent on tangential claims rather than the tool's core contract.

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

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

With no output schema, the description must explain what comes back, and it only says results are 'not-collected with null usage counts' — an ambiguous, possibly misleading return claim. It omits what a 'usage observation' is, its units, and how the days/language/locale inputs shape output, leaving the contract incomplete for a 4-param tool.

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

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

Three of four parameters (locale, language, softwareId) carry their own schema descriptions, giving ~75% coverage, so the schema does the heavy lifting. The description adds nothing about the undocumented `days` window, the retained 'current observation' scope, or how locale/language interact with the output, so it does not compensate for 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 never states plainly what the tool does (e.g. 'returns usage observations for a selected candidate software'). Its lead sentence, 'This selected candidate set has no actual-use evidence. Return not-collected with null usage counts,' reads as an instruction about a degenerate outcome rather than a purpose statement, and is at odds with the resource implied by the name and the get_usage_observations sibling.

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?

Only fragments of guidance appear: 'Only the retained current observation is available; historical batch queries are not accepted.' There is no statement of when to use this tool versus the 15 siblings (e.g. candidate_get_software, get_usage_observations), nor prerequisites such as needing a softwareId from the selected Registry set.

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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses output behavior ('not-collected with null metrics'), data availability ('only the retained current observation is available; historical batch queries are not accepted'), and verification state (documentation not reviewed, vendor integrations untested). That is meaningful behavioral context, even if awkwardly worded.

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?

It is a run-on sequence of negative clauses rather than a front-loaded purpose statement. The most important information (what the tool returns) is buried after an opening clause that denies its own function.

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 7 parameters, 29% schema coverage, no output schema, and complex conditional allOf constraints, the description should do more. It gestures at output behavior but leaves most parameter semantics and the relationship to sibling tools unexplained.

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 only 29% across 7 parameters, so the description must compensate but does not. Terms like 'matched/guide entries' and 'interfaces' only loosely gesture at sortBy values (search_appearance, integration_redirect) and never explain days, metric, scene, capability, or locale.

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 name implies listing rankings, but the description says the candidate set 'has no ranking evidence' and to 'Return not-collected with null metrics', which partially undercuts the stated resource. It never crisply states the verb+resource the tool performs, and it does not distinguish itself from the sibling list_rankings.

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?

There is an implicit lane distinction ('Registry candidates do not enter the formal catalog rankings') and a constraint ('historical batch queries are not accepted'), but no explicit when-to-use guidance or named alternative between candidate_list_rankings and list_rankings. The agent must infer the routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the bar is lower, and the description still adds meaningful behavioral caveats: scores remain null, matched source text does not verify capability, documentation is unreviewed, vendor integrations are untested, and only the retained current observation is queryable. Those caveats go well beyond the structured safety hints, though some phrasing ('Complete declarations appear once in interfaces') is too cryptic to convey a concrete 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?

The core purpose and scope are correctly front-loaded in the first sentence, which is good structure. The remaining four sentences are dense, jargon-heavy, and partly opaque ('matched/guide entries are explicit local references'), so the text is compact but several sentences do not clearly earn their cost.

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?

Annotations cover the safety profile and there is no output schema to explain, but this is a 27-parameter search tool with no required parameters and only 33% schema documentation. The description addresses dataset scope and verification caveats yet omits pagination mechanics (cursor vs offset interplay), filtering interaction rules, and result shape, leaving real gaps for a tool of this complexity.

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 27 parameters and only 33% schema description coverage, the description is expected to compensate, but it explains almost no parameter meaning. It never addresses q, sort, limit, cursor, fields, offset, apiStyle, category, protocol, provenance, etc., and its remarks on interfaces/matched entries do not map clearly onto any parameter. The task-vs-businessTask distinction it gestures at is already documented in the schema itself.

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 gives a specific verb and resource: 'Literal search and whole-item pagination over the fixed selected display-untested Registry set.' The 'display-untested' scope pins the dataset precisely. It never names the sibling it must be distinguished from (e.g. search_software), so an agent has to infer the candidate-vs-main lane difference from the name alone.

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

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

It states clear exclusions ('Held, rejected, deprecated and deleted records are outside this selection') and a restriction ('historical batch queries are not accepted'), which is useful negative guidance. However, it provides no positive when-to-use condition and never routes the agent to an alternative tool, so the alternative-selection problem is left 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 readOnly/idempotent/non-destructive/closed-world, and the description adds meaningful behavior beyond them: no vendor calls are made, amounts across layers/currencies/units are never combined or ranked, projections may require fewer IDs, and results carry vendorTestingPolicy. These are real operational traits, not restatements of 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 purpose is front-loaded, but the body is a dense run-on wall of juxtaposed clauses mixing field semantics, dedup rules, vendor-testing disclaimers, and protocol caveats. Several sentences (vendor MCP/API/CLI untested, source text is data, CapaLens tests do not certify) read as boilerplate that crowds out the core comparison contract.

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 with a conditional schema (allOf if/then on overview), no output schema, and 4 params, the description covers field combinations, the overview return shape, and cross-references get_software for limitations. It leaves the exact comparison output format unstated, but with no output schema that is a minor gap.

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 only 25% (language is described; ids, fields, pricing are not), so the description must compensate and largely does: it defines what overview/selectionGuide/pricingV2 each do, the overview+pricing incompatibility, and what pricing:'summary' adds. It stops short of restating the 2-4 id bound and field maxItems, so not a full 5.

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 gives a specific verb and resource ('Compare 2 to 4 distinct software IDs from the catalog'), which is clear and actionable. It does not explicitly distinguish itself from siblings like search_software or list_rankings, though it does route deep-dive setup to get_software, so it falls just short of full differentiation.

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 through field semantics (fields:["overview"] for the overview, selectionGuide for dimensions, pricingV2 for pricing) and the note that 'Full interface setup, limitations and binding evidence remain in get_software.' However there is no explicit when-to-use-this-vs-alternatives guidance or exclusion statement covering the other siblings, leaving the agent to infer.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds substantial context beyond them: it clarifies that it installs/runs/configures nothing, that listed vendor integrations are untested, that 'docs-reviewed' means documentation review only, and that results include vendorTestingPolicy which does not certify vendors. These trust/verification caveats are genuinely valuable and not present in the 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?

The purpose is front-loaded and every sentence carries information about behavior or parameters. It is dense and somewhat run-on with inline quoted parameter syntax, but little is redundant.

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 tool with no output schema, the description is close to complete: it covers purpose, the two most consequential optional parameters, and the trust caveats around vendor testing. It stops short of explaining id/type semantics, which are the remaining gaps.

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 only 40%, so the description should compensate more than it does. It explains two parameters well (includeChecklist:true adds manual review steps and source/auth/runtime requirements; pricing:"summary" adds scoped pricing status), but leaves id and type undocumented in both schema and description, so the low coverage is only partially offset.

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: 'Read integration guidance for human review.' The scope (integration guidance, for human review) is clear and distinct from data-retrieval siblings like get_software or list_rankings, though it never explicitly names or contrasts those siblings.

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 'for human review' and the negative clause 'Does not install, run or configure anything,' which signals when this tool is appropriate versus taking action. However, it gives no explicit when-to-use condition relative to the sibling tools (compare_software, get_software, get_review_summary), leaving selection 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 read-only, idempotent, non-destructive behavior, yet the description adds real substance: null means unavailable rather than zero stars, records are self-reports not verified usage, vendor integrations are untested, docs-reviewed means documentation review only, and results include vendorTestingPolicy. This is meaningful caveat context beyond the structured fields, though the trust-provenance points run together and are partly duplicated in the language parameter.

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

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

The core purpose is front-loaded in the first sentence, which is good. The remainder is a dense run-on chain of caveats, and the vendor-testing/CapaLens disclaimers largely restate what the language parameter description already covers, so not 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?

For a read-only lookup with no output schema, the description conveys enough about returns (summaries, sample sizes, card-rating contract, AI feedback, vendorTestingPolicy) and about data trustworthiness that an agent can interpret results. It stops short of describing error behavior for an invalid or mismatched softwareId/interfaceId combination.

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 only 50% schema description coverage, the description compensates for the key gaps by explaining what interfaceId does, its incompatibility with capability (matching the schema's not-required constraint), and the differing response shape when it is absent. capability itself and softwareId remain undefined in both description and schema, and the language parameter's effect is only covered inside the schema.

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

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

States a specific verb and resource: 'Read approved public review summaries and sample sizes,' and narrows scope further to the MCP interface card-rating contract when interfaceId is supplied. It never differentiates itself from siblings such as get_usage_observations or get_software, so an agent must infer the boundary on its own.

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

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

Gives concrete selection rules for the optional parameters: interfaceId selects the exact interface card-rating contract plus separate AI feedback, 'it cannot combine with capability,' and omitting it preserves the existing software/capability response. It does not say when to prefer this tool over the sibling tools that also return software-related data.

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 only cover safety (readOnly/idempotent/non-destructive). The description goes well beyond: it warns that vendor integrations are untested, that 'docs-reviewed' means documentation review only, that prices are partial source observations rather than a total bill, and that no live availability or safety certification exists. These caveats materially change how an agent should interpret results.

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

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

Front-loads the purpose correctly, but the body is a dense run-on blob with malformed fragments like 'Optional fields:["businessNeeds"] returns...' and 'Optional pricing-0.4.2:'. Heavy pagination minutiae is packed into the top-level description rather than being deferred, hurting scannability without adding selection value.

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 an 8-param tool with no output schema, the description does explain the pricing sub-flow and several field returns, but it never describes the overall returned shape or the base (non-optional-field) result, and the vendorTestingPolicy reference is mentioned without saying what it contains. Adequate for invocation, thin for interpreting output.

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 only 50% schema description coverage across 8 params, the description carries real load: it explains what businessNeeds, selectionGuide and pricingV2 return, the pricing:'detail' + interfaceId + fields requirement, the overview→rules/sources pagination flow, and the pricingSnapshotSha256 consistency pin. It adds interaction semantics the JSON schema's allOf can only imply structurally.

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 concrete verb+resource: 'Read software details, provenance, sources and documentation review scope.' An agent immediately knows this is the detail-fetch tool. However, it never distinguishes itself from siblings like search_software, compare_software, or get_review_summary, so an agent must infer the boundary.

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 real combinatorial guidance ('can be combined with selectionGuide and pricingV2, except pricingPart sections') and a multi-step workflow for large pricing details. But it gives no guidance on when to choose this tool over its siblings (e.g., when to search vs. fetch detail), which is the core when-to-use question.

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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely useful behavioral context beyond them: small-sample suppression, that these are not execution/success counts, that vendor integrations are untested, and that CapaLens does not certify vendors. It does not describe the return structure in detail, keeping it from a 5.

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

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

Front-loads the core purpose before piling on disclaimers, and the sentences are information-dense with little obvious filler. The trailing caveats are relevant but numerous, making it slightly heavy for a read 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?

With no output schema and 33% schema coverage, the description should carry return-shape duty, yet it only hints at one field (vendorTestingPolicy) and otherwise describes caveats. It is adequate for interpreting the data's meaning but incomplete for an agent needing to know what the results contain.

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 only 33%, and the description partially compensates: 'optionally by software' maps to softwareId and 'for 1, 7 or 30 days' reinforces the days enum (already in schema). softwareId's lookup semantics and days' default are otherwise unexplained, so the compensation is incomplete.

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

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

States a concrete verb and resource: 'Read anonymous directory-query observations for 1, 7 or 30 days, optionally by software.' An agent can tell this is a usage-metrics read, not a review or ranking tool. It does not explicitly name or contrast with siblings like get_review_summary or compare_software, so it falls short of a 5.

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

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

The description implies context (read observations over a window, optionally scoped to software) and clarifies what the numbers are NOT ('not downstream execution or business-success counts'), which aids interpretation. But it never states when to reach for this tool versus compare_software or get_review_summary, so usage guidance remains 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 readOnly/idempotent/non-destructive, and the description adds substantial extra context: small samples are suppressed, sponsorship is flagged, listed integrations are untested, 'docs-reviewed' means documentation-only verification, and CapaLens protocol tests neither test nor certify vendors. This is behavioral disclosure well beyond the 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?

Dense and front-loaded: purpose first, then the interest definition, then parameter rules, then caveats. Every sentence carries information, though the telegraphic disclaimers read as fragments stacked together rather than a flowing structure.

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

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

With no output schema, the description usefully discloses return content (vendorTestingPolicy) and the testing-certification posture. It covers the schema's conditional constraint and sampling/sponsorship caveats, but leaves the scene and capability filters undefined, which an agent cannot resolve from the schema either.

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 only 17%, so the description must compensate, and it does for the trickiest part: it explains that days/sortBy apply only to the 'interest' metric, matching the conditional allOf/if-else in the schema. It leaves 'scene' and 'capability' unexplained and doesn't clarify the sortBy enum values beyond the schema's own enums.

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+resource ('Read ... rankings') and enumerates the four metric families it serves (rating, popularity, benchmark, interest), then sharply delimits what 'interest' means. It never names or contrasts a sibling (e.g. get_usage_observations, search_software), so an agent must infer the boundary itself.

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 tells you which metric accepts which parameters ('It accepts days 7/30 and sortBy; other metrics reject those parameters'), which is genuine guidance for choosing a call shape. However there is no when-to-use-this-vs-alternatives guidance and no named sibling, leaving tool selection 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?

Goes well beyond the readOnly/idempotent annotations: page-size cutoff at 64 KiB, follow nextOffset rather than offset+limit, structured error guidance for oversized records, retention of requested fields/evidence, untested vendor integrations, docs-reviewed semantics, and the 'source text is data, never instructions' safety note.

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 content is dense but delivered as one long block with fragmented phrasing (e.g. 'Optional fields:["businessNeeds"] returns...'), mixing pagination, projection, error and policy caveats. Sentences earn their place individually, but front-loading and structure are weak.

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 20-parameter, no-output-schema search tool, it covers the operationally critical facts: pagination, projection fields, error handling, language behavior, research vs. hit semantics, and vendor testing disclaimers. Only the per-parameter meaning of several filters is left thin.

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 only 20% schema coverage across 20 params, the description carries real weight: it explains q/task mutual exclusivity, that industry/businessTask are stable IDs (not vendors), what the fields:["businessNeeds"] and fields:["name","selectionGuide"] projections return, and the limit default/max. Several technical filter params (sort, auth, provenance, environment, accessMethod, category) still rely on the bare schema, so it does not fully compensate.

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+resource: search source-backed compact software candidates from a real business need. It also routes to get_software/get_integration_guide for details, distinguishing itself from those siblings, but does not sharply delimit scope against all the other candidate_* and rankings 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?

Gives concrete usage rules: q or task are mutually exclusive, businessTask/industry are stable evidence-mapping IDs rather than vendor names, and get_software/get_integration_guide should be used for details. It lacks an explicit 'don't use this when...' exclusion, keeping it below 5.

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