FactReason

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. The description adds useful behavioral context by specifying what kind of analysis is performed and what result categories the agent can expect, though it does not address version-omission behavior.

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

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

Two focused sentences: the first establishes the core operation and outputs, the second gives a direct routing instruction. No filler or redundant restatement of the tool name.

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

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

The description is largely complete for an agent selecting and invoking this tool, especially with the output schema present and a sibling alternative named. The main gap is the implicit assumption that two versions are compared while only service is required, leaving the default comparison behavior under-specified.

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 already documents all three parameters with descriptions, including examples for service and the roles of fromVersion/toVersion, so baseline is 3. The description adds little parameter-level meaning beyond the phrase 'Compare two versions', and it does not clarify behavior when the optional versions are omitted.

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 identifies a specific verb-resource pair: comparing two versions of a third-party API and returning breaking changes. It lists concrete outputs (removed endpoints, parameter type changes, removed request body fields, migration guides), and the closing sentence distinguishes it from factreason_package_upgrade_advisory.

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 explicitly states when NOT to use this tool: for npm or PyPI packages, use factreason_package_upgrade_advisory instead. This gives the agent a clear decision rule and differentiates the tool from a key 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?

Annotations already declare read-only, idempotent, non-destructive, but the description adds 'Uses metered access' (a cost implication) and 'returns matches or nearest services' (fallback behavior). This goes beyond the structured annotations and adds useful behavioral context, though not extremely rich.

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

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

Two sentences, no fluff. First sentence states purpose; second covers usage modes, caveats (metered access, no modification), and alternative tool. Every sentence carries meaningful content, and it is front-loaded with the primary action.

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

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

Given the tool has 0 required params, 2 optional, full schema coverage, and an output schema (not shown but present), the description covers all necessary aspects: purpose, usage patterns, behavioral notes, and a clear alternative. It is complete for an agent to decide when and how to invoke it.

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 descriptions cover both parameters (query and service), so baseline would be 3. The description adds semantic meaning by explaining how to combine them: service alone, query alone, or together, and how they scope the search. This enriches understanding of parameter roles beyond mere field descriptions.

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

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

The description clearly states the tool searches exact request and response schemas for third-party API endpoints, and differentiates usage modes (service alone, query alone, or combined). It explicitly distinguishes from a sibling tool (factreason_integration_brief) by recommending it for one-callable requests, making the purpose and scope precise.

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 explicit when-to-use guidance: passing service alone lists endpoints, adding query narrows by path/operation, or query alone across services. It also gives a clear exclusion: prefer factreason_integration_brief for a single callable request. This directly helps agent decide between this and an alternative.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context: it returns nearest-service suggestions, marks undocumented details as unstated rather than guessing, and uses metered access. No contradiction with annotations.

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

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

The description is three sentences long, front-loads the core purpose, and includes only actionable details: what is returned, how unknowns are handled, metering, and the preferred alternative. Every sentence earns its place.

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

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

Given a single required parameter, 100% schema coverage, rich annotations, an output schema, and clear sibling context, the description fully covers the behavioral and selection needs. It explains the result shape, fallback behavior, honesty policy, and access cost.

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% and the single 'service' parameter is already described with an example, so the description does not need to add much. It reinforces that the tool handles one third-party API at a time, but that does not materially extend the schema's meaning.

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

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

The description uses a specific verb ('Get') plus the exact resource: publisher-declared authentication schemes, scopes, rate-limit headers, and error codes for one third-party API. It clearly distinguishes itself from siblings like factreason_integration_brief by naming the playbook's focused scope.

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

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

It explicitly states when to use this tool versus an alternative: 'Prefer factreason_integration_brief when assembling a complete API call.' It also notes metered access, implying careful invocation, and clarifies the tool supports one service at a time.

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 annotations, the description discloses metered access, returning matches or suggestions, the backward-compatible default for responseFormat, and the caveat to confirm critical values against datasheets. This meaningfully enriches the readOnly/idempotent annotation data.

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?

Each sentence earns its place: primary function, lookup modes, response format guidance, and a safety caveat. The description is front-loaded and compact without fluff.

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

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

Given the output schema exists, the description need not explain return values. It covers the two input modes, precedence, responseFormat semantics, metered access, and a datasheet verification caveat—complete for a moderately complex lookup 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 coverage is 100%, so the baseline is 3. The description adds value by explaining partNumber precedence, the distinction between exact lookup and capability search, and why compact responseFormat is recommended for exact lookups—information not fully captured in the schema.

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

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

The description uses a specific verb and resource: "Look up electronics component pin assignments, voltage range, package, and alternatives," which clearly defines the tool's function. It distinguishes itself from sibling tools like factreason_api_schema or factreason_deprecation_scan by focusing on component data, not API lifecycle or auth operations.

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

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

It gives clear usage context: pass exact partNumber for a specific component, use query for capability search, and notes precedence when both are supplied. It does not explicitly mention sibling alternatives or exclusions, but the mode guidance is strong and actionable.

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

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

With all annotations false, the description carries the full burden. It adds meaningful behavior: instant issuance, no human/signup/card, one-off trial credit, free/never metered, and email optional with a key always issued. Minor inconsistency with schema's 'Improves the chance' vs description's 'only affects whether' prevents 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?

Three sentences, front-loaded with purpose, and every sentence adds value. The 'CALL THIS FIRST' emphasis is clear and efficient. No filler or repetition.

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

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

The tool is simple, with one optional parameter and an output schema. The description covers when to call, what it returns (a key with trial credit), free usage, email semantics, and the retry pattern. Given the output schema exists, no need to detail return values. The description is complete for this tool's context.

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

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

The schema already covers the email parameter 100% (optional, improves chance of trial credit). The description repeats this and adds 'only affects whether', which slightly contradicts the schema's 'improves the chance'. Since schema coverage is high, baseline 3 is appropriate, and no additional parameter meaning is added.

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

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

The description clearly states the tool's purpose: 'Get a FactReason API key for yourself' with specific details about instant issuance, no signup, and no card. It distinguishes itself from sibling tools by focusing on key creation rather than API discovery, schema, or auth playbooks.

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?

Explicit usage guidance is provided: 'CALL THIS FIRST if you have no key, or as soon as any FactReason tool returns HTTP 402 Payment Required — then retry the original call with the key.' It also notes the tool is free and never metered, reinforcing when it is appropriate to use.

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?

While annotations indicate non-read-only and external world interaction, the description goes far beyond by explaining that it creates an external checkout session, does not charge the card, cannot complete payment, and that credit is applied only after human payment completion. It also notes the tool is not metered. This provides valuable behavioral context the annotations do not cover, with no contradictions.

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

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

The description consists of four sentences, each conveying essential information: purpose, side-effect behavior, user action required, and usage trigger. It is front-loaded with the main purpose and avoids unnecessary wording. While not as terse as a single sentence, the extra length is justified by the need to explain external payment flow clearly.

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 one parameter and an existing output schema, the description is complete. It covers purpose, usage conditions, behavioral caveats, and the critical requirement to return the URL to a human. The presence of an output schema means the return value need not be explained. No significant gaps remain for an agent to correctly invoke this 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?

The schema description provides full coverage for the single parameter (amountUsd) with min, max, and common block examples. The tool description itself adds no additional parameter semantics, so it does not exceed the baseline of 3 when schema coverage is high. The description does not redundantly repeat schema information, which is acceptable.

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

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

The description clearly states the tool creates a Stripe Checkout URL for adding prepaid credit to the calling Bearer API key. It distinguishes itself from sibling tools (which are about API discovery, auth, and key management) by specifying the exact resource and action. The verb 'create' and specific resource 'Stripe Checkout URL' make the purpose highly unambiguous.

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

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

The description explicitly instructs when to use the tool: after an HTTP 402 or when balance is low. It also clarifies that the tool itself is not metered, which prevents misuse. It and states that the agent cannot complete payment, so the URL must be returned to a human, providing clear usage context. No alternatives exist among siblings, so no exclusions are 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 readOnlyHint=true and destructiveHint=false, and the description adds crucial behavior: 'Uses metered access when findings exist.' This is a meaningful addition beyond the annotations, as it signals a cost/limit consideration. A small deduction because it doesn't specify what happens to the results or if there's any deprecation-specific data returned.

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

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

Three sentences, each earning its place: purpose, usage pattern, and caveat. It's dense but not bloated. Losing a point for front-loading critical info (purpose) well but the metering note feels slightly secondary, though still relevant.

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 scanning tool with clear annotations and an output schema, the description is quite complete. It explains the tool's niche (deprecation scanning) and distinguishes from siblings. The only minor gap is not explaining what 'metered access' means for the user, but the sibling reference and annotations cover most context needs.

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% and the schema already describes 'Optional service filter' and 'Optional endpoint paths to check'. However, the description adds important context about how to use the filters ('Omit filters...', 'pass service to limit one API', 'add endpoints to check selected paths'). The baseline for 100% coverage is 3, and the description earns an extra point for giving semantic meaning to the parameters.

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

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

The description uses a specific verb ('Scan') and names the resource ('publisher specifications') and subject matter ('deprecated endpoints or parameters, sunset dates, replacement operations'). It clearly differentiates itself from siblings by explicitly pointing to `factreason_api_breaking_changes` for broader changes.

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 clear when-to-use guidance: 'Omit filters for the catalogue-wide view, pass service to limit one API, and add endpoints to check selected paths.' It also references the alternative sibling tool by name, which addresses the 'vs alternatives' criterion directly.

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 (readOnly, idempotent, non-destructive), the description discloses additional behavioral details: it uses metered access (implying cost or rate limits) and specifies the output structure (ranked services, example endpoints, next step). This enriches the agent's understanding without contradicting the annotations.

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

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

The description is succinct, covering purpose, usage, output, and caveats in three sentences without redundancy. It is well-structured, front-loading the core function and then adding usage guidance and alternative conditions.

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

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

Given the schema (one parameter) and annotations (read-only, idempotent), the description completes the picture by explaining the return format, the metering aspect, and the decision tree for using this tool versus the sibling. No critical information is omitted for effective selection and 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?

The sole parameter 'capability' is described in the schema with examples, and the description reinforces this with additional examples and guidance on being concise. The parameter's purpose and expected value are fully explained, achieving complete coverage.

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

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

The description clearly states the tool's primary function: finding third-party APIs for a capability when the provider is unknown. It also differentiates from the sibling tool by explicitly instructing to use factreason_integration_brief when the provider is already known.

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 provides explicit conditions for when to use this tool ('when the provider is unknown') and when not to (calling the alternative when provider is known). It also gives a concrete example of a capability input ('send an SMS'), clarifying the expected parameter format.

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 behaviors. The description adds metered access and explains responseFormat backward compatibility, including tokenizer-measured context savings, providing valuable behavioral context beyond annotations without contradiction.

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

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

Two concise, front-loaded sentences with no redundancy; each phrase contributes directly to understanding the tool's purpose, usage, and behavior.

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

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

Given the output schema exists and annotations cover safety, the description covers usage context, response format choices, and the alternative tool, making it complete for an API brief compiler.

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 covers 100% of parameters with detailed descriptions. The description reinforces service requirement, clarifies endpoint's optional narrowing role, and explains responseFormat's compact vs full purpose, adding some semantic value 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?

Description clearly states the tool compiles a single callable third-party API brief with explicit components (base URL, auth, params, body, response codes). It also distinguishes from the sibling factreason_api_schema by advising when to prefer that tool, ensuring clear 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?

Explicitly states that service is required and endpoint optionally narrows the operation, and directly recommends factreason_api_schema for multiple endpoints, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context: this is a 'read-only metered lookup', 'misses are never billed', 'every API key carries one-off trial credit', and responseFormat changes affect context size while staying backward-compatible. No annotation contradiction exists.

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

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

The description is compact and well-structured: it opens with the core purpose and evidence, then covers the format switch, billing/read-only semantics, then alternatives. Every sentence earns its place and there is no repetition 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?

Given the output schema exists, the description does not need to explain return-value structure. It fully covers the required context for a moderately complex comparison tool: scope, exact-match semantics, response formats, billing, authentication trial credit, and alternatives. The agent has enough to select and invoke this tool correctly.

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

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

The input schema provides full parameter descriptions, so the baseline is 3. The description adds value by clarifying that responseFormat='compact' yields tokenizer-measured context savings while the default is backward-compatible 'full', and by enumerating relevant metadata fields such as yanks, exports, module format, runtime floors, peers, and licences.

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

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

The description clearly states the tool compares two exact published npm or PyPI versions and returns publisher-declared registry metadata changes. It is explicit about the resource (package metadata), specific verbs ('compare', 'return'), and differentiates itself from factreason_api_breaking_changes.

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 it for package metadata; use factreason_api_breaking_changes for a third-party HTTP API, and consult changelogs for behavioural changes.' It also clarifies metering, billing behavior, and response format trade-offs, enabling an agent to select this tool over siblings.

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?

Even with annotations present (readOnlyHint:false, idempotentHint:true), the description adds substantial behavioral context: the 50-watch hard limit per Bearer key, the authentication requirement, signed callback semantics, and duplicate/unsafe rejection behavior. It richly reinforces the idempotentHint by explaining exactly how duplicate registration is handled, and clarifies that despite being a write operation, it intentionally avoids immediate spec ingestion—semantics no structured field could capture.

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 dense sentences in under 65 words cover purpose, authentication, limits, success criteria, and exclusions. The structure is front-loaded with the primary verb-object, then constraints, then a final clarifying negative. Every clause earns its place with no filler, redundancy, or schema repetition.

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

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

Given the tool's moderate complexity (a stateful subscribe action) plus the presence of an output schema, the description fully covers the open questions: side effects are explicit (watch creation), failure modes are disclosed (duplicate/unsafe rejection), limits are quantified (50 per key), and the temporal scope ('after later spec changes') clarifies it won't fire retroactively.

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 of 3 is appropriate; the schema already provides format (uri), constraints, and clear examples for both parameters. The description marginally enriches webhookUrl by framing the poll-vs-callback tradeoff, but it largely restates what the schema fields already declare. No parameters are undocumented, so nothing is missing, but the description adds little parameter-specific insight 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 opening phrase 'Create a persistent specification watch for one service' uses a specific verb and resource with clear scope, and the 'This does not ingest a specification immediately' sentence preempts a likely conflation with other tools. Within the sibling set (breaking_changes, deprecation_scan, api_schema), this description unambiguously identifies the subscribe/watch responsibility, clearly differentiating it from one-off analysis tools.

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

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

The description provides an explicit either/or usage decision: 'Without webhookUrl, read future events from the polling endpoint; with a public HTTP(S) URL, FactReason sends signed POST callbacks.' This gives strong contextual guidance for the tool's two modes. However, it does not literally name sibling alternatives (e.g., no 'use factreason_api_schema instead for...' phrasing), and the 'does not ingest' exclusion is slightly delayed rather than front-loaded as a warning.

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