FactReason

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

Annotations already declare this a safe, idempotent read (readOnlyHint, destructiveHint=false), so the safety profile is covered. The description adds real behavioral value by specifying the analysis performed (version diffing for breaking changes) and that migration guides are produced. Return format is not described, but an output schema exists, so that omission is acceptable.

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, both earning their place: the first defines capability and outputs, the second handles sibling routing. The core purpose is front-loaded with no preamble 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?

With an output schema present, annotations covering safety, and 100% parameter description coverage, the description carries everything an agent needs: what the tool analyzes, what it returns, and which sibling to use instead. No meaningful gap remains.

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 all four parameters (apiKey, service, fromVersion, toVersion) are documented in the schema itself. The description only implies the two-version comparison and adds no syntax, defaults, or examples beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Compare two versions of a third-party API') and enumerates the concrete outputs (removed endpoints, parameter type changes, removed request body fields, migration guides). It also names the sibling it is not (factreason_package_upgrade_advisory), so an agent can distinguish it without opening any schema.

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

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

Explicitly routes the agent away from this tool for npm/PyPI packages by naming factreason_package_upgrade_advisory, which is a clear alternative. However it gives no guidance on when to prefer this over other version-related siblings such as factreason_deprecation_scan.

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. The description adds value beyond that: 'Uses metered access' (a cost implication not in the annotations) and 'returns matches or nearest services' (a fallback behavior worth knowing). It stops short of describing latency or result ranking, so a 4 rather than 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?

Two sentences, front-loaded with the primary purpose, then the mode semantics and the sibling alternative. No filler and every clause carries information.

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, return values need no explanation. Combined with full schema coverage and rich annotations, the description covers purpose, modes, fallback behavior, cost, and the alternative tool — nothing material is missing 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 100%, so baseline is 3, but the description goes beyond the schema by explaining how parameters combine — service alone, service+query, or query alone — which the schema cannot convey since every property is individually marked optional.

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 precise verb and resource: 'Search exact request and response schemas for third-party API endpoints.' This is distinct from siblings like factreason_discover_api and factreason_component_spec, and it explicitly names factreason_integration_brief as the alternative for a different need.

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?

Explicitly enumerates the invocation modes: 'Pass service alone to list its indexed endpoints, add query to narrow by path or operation, or use query alone across services.' It also names the sibling alternative and the condition ('for one callable request') that selects it.

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, so the safety profile is covered; the description adds real value beyond them by disclosing metered access (cost), fallback behavior ('nearest service suggestions'), and the honesty trait of marking undocumented details 'unstated rather than guessing'. It does not state rate-limit or latency behavior for the tool itself, keeping it out of the 5 band.

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 front-loaded sentences with no filler: purpose first, then fallback/honesty behavior, then the sibling routing. Efficient, though the return-behavior and routing clauses could be tightened slightly.

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 2-parameter read-only tool with an output schema and full schema description coverage, the description covers purpose, auth key mechanics indirectly, metered cost, fallback behavior, and sibling routing. Nothing an agent needs to call it 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 description coverage is 100%: the apiKey parameter's header-vs-key guidance and the service example are fully documented in the schema. The description adds no parameter-level syntax or format detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb (get) and a concrete resource set (publisher-declared auth schemes, scopes, rate-limit headers, error codes) scoped to 'one third-party API'. It also differentiates itself by naming the sibling factreason_integration_brief and the distinct job it does.

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?

Explicitly routes the agent: 'Prefer factreason_integration_brief when assembling a complete API call,' giving a clear alternative and the condition that selects it. It lacks an explicit when-not statement (e.g., what to use when the service is unknown or when no playbook exists), so it falls short of the top band.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds what annotations cannot: metered access, that results may be matches or suggestions rather than exact hits, and a datasheet-verification caveat. The compact/full output-shape tradeoff is also disclosed. Minor omission is any note on rate limits or what 'suggestions' implies for reliability.

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 capability, then mode selection, then format, then the caveat. Four sentences, each carrying distinct information. Slightly dense but no filler; the caveat sentence is arguably the least load-bearing but is defensible for engineering data.

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 not be described, and the auth parameter is documented in the schema. The description supplies mode selection, precedence, metered access, and a correctness caveat, leaving little an agent needs to call it correctly. A note on pagination or result-count limits would close the remaining 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 coverage is 100%, so the baseline is 3, but the description adds genuinely new meaning: the precedence order between partNumber and query, and the tokenizer-measured context savings of responseFormat=compact versus the backward-compatible full default. That is substantive guidance beyond the enum and property docs.

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

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

States a specific verb and resource ('look up electronics component pin assignments, voltage range, package, and alternatives') and enumerates the exact fields returned. It is clearly distinct from every sibling, which are all API-lifecycle tools (breaking changes, schema, auth, deprecation).

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 an explicit routing rule between the two modes ('Pass exact partNumber for one component or query for a capability search') and resolves the conflict case ('partNumber takes precedence if both are supplied'). No sibling alternatives are named, but none of the siblings overlap functionally, so this gap is minor.

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 say readOnlyHint=false and idempotentHint=false. The description adds the materially important traits: the tool is free and never metered, a key is always issued, trial credit may or may not be granted, and the email never blocks issuance. These are exactly the facts an agent needs before spending a call.

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 outcome, then the trigger conditions, then the retry mechanics, then the free/email caveats. Every sentence carries distinct operational 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?

An output schema exists, so return values need not be explained. With one optional parameter, full schema coverage, annotations, and explicit recovery instructions for the 402 case, nothing needed to call this 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 coverage is 100%, so the baseline is 3. The description nevertheless adds meaning beyond the schema by clarifying that email 'only affects whether trial credit is granted' and that a key is issued either way, which resolves the ambiguity in the schema's 'improves the chance' wording.

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 a FactReason API key') plus the distinguishing conditions (no signup, no card, instant). It is unmistakably different from the sibling documentation/spec tools, which do not issue credentials.

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 explicit when-to-use triggers: 'CALL THIS FIRST if you have no key' and 'as soon as any FactReason tool returns HTTP 402 Payment Required'. It also states the follow-up action (retry with the key via apiKey argument or Authorization header), so the agent knows both when to call and what to do after.

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 annotations: it discloses that an external checkout session is created but no card is charged, that payment cannot be completed by the agent, that credit is only applied after a human pays, and that the tool itself is not metered. This is exactly the extra behavioral context annotations cannot convey.

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?

Four tight sentences with the core action front-loaded followed by the critical human-handoff constraint and the usage trigger. 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?

An output schema exists, so return-value explanation is unnecessary; the description instead covers the payment lifecycle and the agent's limitation. Nothing an agent needs to call this safely and correctly is absent.

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 both parameters (apiKey, amountUsd) are already fully documented in the schema, including the key-omission guidance. The description adds only the framing that the key is 'the calling Bearer API key', which is marginal; baseline 3 applies.

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

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

States a specific verb and resource ('Create a Stripe Checkout URL for adding prepaid credit') and scopes it to the calling Bearer API key. No sibling tool overlaps with this purpose, so an agent can distinguish it immediately.

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 an explicit trigger ('Use after HTTP 402 or when balance is low') and an explicit operational constraint ('You CANNOT COMPLETE THE PAYMENT YOURSELF, so return the URL to a human'). With no competing sibling, no alternative routing is needed.

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 safety profile is covered. The description adds a real behavioral trait not in the annotations — 'Uses metered access when findings exist' — which tells the agent about cost incurred on results. It does not add return-format or rate-limit detail, but the output schema covers returns, so a 4 is warranted.

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 tight sentences: purpose first, then scoping mechanics, then the metering note and the routing pointer to the sibling. No filler and no repetition of what the schema or annotations already state.

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 0 required params, 100% schema coverage, full annotations, and an output schema, the remaining burden on the description is usage and cost context — both supplied. An agent has everything needed to decide when to call this versus factreason_api_breaking_changes and how to scope the call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: what happens when the optional filters are omitted (catalogue-wide) and how service and endpoints compose (endpoint paths are checked within the selected service). That default/combination behavior is genuinely beyond the per-field schema text.

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 (scan) and resource (publisher specifications) plus the exact artifacts it surfaces: deprecated endpoints/parameters, sunset dates, and replacement operations. It explicitly names the sibling it is not (factreason_api_breaking_changes), so an agent can route correctly without opening either schema.

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

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

Gives concrete invocation guidance — omit filters for the catalogue-wide view, pass service to scope to one API, add endpoints to check specific paths — and names the alternative tool with the condition that selects it ('broader version-to-version changes'). This is explicit when-to-use, how-to-scope, and when-to-use-something-else.

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, so the safety profile is covered. The description adds a trait annotations do not: "Uses metered access", a cost/billing consequence the agent should know before calling. It stops short of describing rate limits or quota behavior, so it is strong but not exhaustive.

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 purpose and the unknown-provider condition, then the return shape, then the routing alternative. Every sentence carries distinct 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?

Output schema exists, so the brief mention of ranked services and a next step is enough without enumerating return fields, and annotations cover safety. With metered access disclosed and the sibling routing rule stated, nothing an agent needs to call this 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 description coverage is 100%, so both parameters (including the apiKey header fallback and the capability examples) are already documented in the schema, which sets the baseline at 3. The description's guidance to "Supply a concise capability such as 'sms' or 'manage DNS'" is a mild hint about expected granularity but largely overlaps the schema's own examples.

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 ("Find third-party APIs") plus the narrowing condition "when the provider is unknown", which separates it cleanly from the provider-known path. An agent can distinguish it from factreason_integration_brief without opening either schema.

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

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

Gives an explicit selection rule: use this when the provider is unknown, and names the concrete alternative (factreason_integration_brief) for the known-provider case. Nothing about when to route here versus there 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds value beyond them: 'Uses metered access' discloses a cost/quota trait, and it clarifies the responseFormat default behavior ('backward-compatible default returns the full brief plus compact form'), which the schema does not spell out.

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-loaded with purpose in the first sentence, followed by parameter guidance, format behavior, metered access, and the sibling alternative. Dense but each sentence earns its place; minor redundancy in restating the responseFormat tradeoff that the schema also gestures at.

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 not be explained, and the description still summarizes the brief's contents. Metered access, the required/narrowing parameter roles, and the sibling alternative are all covered, leaving nothing an agent needs to call correctly unstated.

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 baseline is 3, but the description adds real meaning: it notes service is required, endpoint optionally narrows the operation, and explains responseFormat='compact' delivers 'tokenizer-measured context savings' while the default returns the full brief plus compact form. This goes beyond the schema's terse enum 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?

States a specific verb (Compile) and resource (one callable third-party API brief), then enumerates exactly what the brief contains: base URL, auth scheme, required parameters and types, request body, and documented response codes. It also explicitly names the sibling factreason_api_schema as the alternative, so an agent can distinguish the two without opening either schema.

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

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

Provides clear context (service required, endpoint narrows the operation) and an explicit alternative with its selecting condition: 'Prefer factreason_api_schema when exploring multiple endpoints.' It lacks explicit when-not conditions or prerequisites beyond this, so it stops short of a 5.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds genuinely new context: metered read-only billing, misses never billed, one-off trial credit per key, and that 'compact' is tokenizer-measured while 'full' preserves the legacy contract. It also scopes the answer to publisher-declared registry metadata, warning the agent off behavioural inference. It stops short of describing failure modes for an unpublished or nonexistent version pair.

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-loaded with the purpose sentence, then format guidance, then billing terms, then sibling routing – each block earns its place. It is denser than ideal, packing four distinct concerns into one paragraph, but nothing 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?

Output schema exists so return values need no explanation, annotations carry the safety profile, and the description supplies the remaining decision-critical pieces: sibling routing, response format tradeoff, and billing/auth context. An agent has everything needed to call it 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?

Schema description coverage is 100%, so the schema already documents all six parameters including the responseFormat enum and the apiKey/Authorization interplay. The description's 'exact published versions' phrasing reinforces the from/to semantics and frames compact vs full as a context-cost tradeoff, but adds little syntax or format detail 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?

States a specific verb (compare) and resource (two exact published npm or PyPI versions) and enumerates the exact output surface (yanks, exports, module format, runtime floors, peers, licences) with before/after evidence. It also explicitly distinguishes itself from the sibling factreason_api_breaking_changes, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use ('use it for package metadata'), names the competing sibling and the condition that selects it ('for a third-party HTTP API'), and adds a further exclusion ('consult changelogs for behavioural changes'). That is when/when-not/alternatives in one 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?

Beyond the annotations, it discloses the Bearer API key requirement, a concrete 50-watch-per-key quota, the dual webhook/polling event delivery model with signed POST callbacks, rejection of duplicate/unsafe registrations, and the non-immediate-ingest caveat. This is rich operational context the annotations alone do not convey.

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?

Roughly four sentences, all front-loaded and information-dense with no filler. The auth and quota constraints come first, followed by the behavioral branch, which is a sensible ordering.

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 explain return values, and it still covers auth, quota, delivery mode, and the ingest exclusion. Nothing an agent needs to invoke this 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 description coverage is 100%, so the schema already documents all three parameters, including that webhookUrl defaults to polling. The description largely restates this dual-mode behavior with only marginal added phrasing ('read future events from the polling endpoint'), so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Create a persistent specification watch for one service.' This clearly distinguishes it as a watch/subscribe action rather than the scan or schema siblings, though it never names an alternative tool to differentiate itself 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?

It gives a clear condition for the webhook vs polling branch ('Without webhookUrl... with a public HTTP(S) URL...') and adds an exclusion ('This does not ingest a specification immediately'). It stops short of naming sibling tools or the scenario that would favor them.

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