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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial context beyond those: it discloses a per-call cost ('$0.001 USDC or 1000 drops XRP'), states 'read-only, does not execute code', and explains the matched=false contract for catalog misses. This is meaningful behavioral information not encoded in the structured 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?

Four dense sentences, each carrying essential information: purpose, usage precondition, fallback routing, sibling disambiguation, cost, and safety profile. Nothing is redundant; the main action is front-loaded and the additional context is packed efficiently.

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 definition is complete for a diagnostic tool with an output schema. It explains the input requirement, the failure mode (matched=false), the cost, the safe/read-only nature, and how it relates to sibling tools. Since the output schema exists, return values are already documented, and no critical operational detail 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% and both parameters already have clear descriptions: error_log as 'Raw traceback or exception text' and framework as the allowed list. The tool description repeats the framework list but adds no new parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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 ('Match') and resource ('stack trace or exception against known deprecated APIs') and names the exact frameworks (langchain, llamaindex, ollama, xrpl). It also explicitly contrasts with fetch_latest_syntax ('Not for happy-path syntax'), so an agent can distinguish this from siblings without opening the 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?

It gives an explicit precondition ('Use only when you have an error_log'), a fallback action ('matched=false ... then search_ai_framework_docs with the failing symbol'), and a preventive alternative ('Lint source before it crashes with review_framework_code'). It also excludes happy-path syntax with fetch_latest_syntax, leaving no ambiguity about when to call this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces this with the explicit non-actions 'never submits, signs, or moves funds.' It further discloses cost ('$0.001 USDC or 1000 drops XRP'), which is not present in annotations or schema. This adds meaningful behavioral context 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?

The description is four tight sentences: the core action, a usage directive with explicit exclusions, alternatives, and pricing. Every sentence earns its place, and the purpose is front-loaded before the routing guidance. No redundancy or filler.

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

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

Given the tool's low complexity, full schema coverage, and presence of an output schema, the description covers everything an agent needs: what it returns (skeleton plus failure codes), when to use it, what it won't do, alternatives, and cost. There is no missing information that would prevent 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 description coverage is 100% and both parameters (intent, language) are already described in the input schema. The description merely restates the allowed intent values and does not add new information about parameter formats, defaults, or edge cases. Baseline 3 applies because the schema does the heavy lifting.

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 names a specific verb ('Draft') and resource ('typed xrpl.js / xrpl-py skeleton') and narrows scope to payment/trustline/rlusd/channel. It explicitly contrasts itself with fetch_working_example (full script) and review_framework_code (linting), so an agent can distinguish it from siblings without opening schemas.

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

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

It states exactly when to use the tool ('Use when building an XRPL tx') and what it never does ('never submits, signs, or moves funds'). It also names the alternatives and their purpose: 'Prefer fetch_working_example for a full script and review_framework_code to lint Amount/address mistakes.' No ambiguity remains.

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

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

The description complements the annotations by adding the fallback behavior for unknown topics, the read-only nature of the catalog, and the per-call cost. These are behavioral details beyond readOnlyHint, idempotentHint, and openWorldHint. No contradictions 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 front-loaded with the primary purpose and uses a compact sentence. Every sentence adds value: purpose, usage trigger, fallback behavior, alternative routing, and cost/read-only note. 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?

With only two fully documented parameters, an existing output schema, and annotations covering safety, the description provides all necessary context: what the tool returns, when to use it, how it behaves on unknown topics, and how it differs from alternatives. Nothing an agent needs to invoke 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%, and the description adds no new meaning about individual parameters beyond what the schema already documents for 'topic' and 'framework'. The description's mention of 'one topic' and example values is redundant with the parameter descriptions, so the baseline 3 is appropriate.

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: it delivers 'curated working imports, snippets, and migration notes' for a single topic. It also differentiates itself from siblings by explicitly naming what to prefer for other needs (complete runnable file, open-ended lookup, exceptions), so an agent can distinguish this tool 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?

The description gives an explicit trigger: 'Use when writing or migrating a fragment.' It also routes to alternatives with clear conditions—fetch_working_example for complete files, search_ai_framework_docs for open-ended lookup, diagnose_framework_error for exceptions—and explains fallback behavior for unknown topics.

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 include readOnlyHint=true and idempotentHint=true, and the description reinforces them by stating 'does not execute the example.' It also adds valuable non-obvious context: the paid cost ($0.001 USDC or 1000 drops XRP) and the matched=false response semantics, which go beyond what annotations provide.

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

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

Two tight sentences front-load what the tool fetches, then cover usage context, fallback behavior, and cost. No filler or redundant restatement of schema details; every clause 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 4-parameter fetch tool with an output schema, the description fully equips an agent: what it returns (filename, install/run, source), when to choose it, what happens when no example matches, cost, and non-execution guarantee. Nothing needed to invoke 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%, so the schema already documents all four parameters. The description adds some helpful context with goal examples ('agent, rag, chat, payment, rlusd') but does not add meaning beyond what the schema provides for runtime, language, or framework.

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: 'Fetch one complete runnable file' with concrete goal examples (agent, rag, chat, payment, rlusd). Explicitly names its sibling fetch_latest_syntax and explains the distinction, making it easy for an agent to select this tool over alternatives.

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

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

Directly says when to use this tool: 'Use when fetch_latest_syntax snippets are too small to execute.' It also provides the fallback behavior ('matched=false means no catalog example — then fetch_latest_syntax'), giving explicit 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 supply readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable context: 'catalog-backed, does not execute code' reinforces no side effects, and the explicit pricing ($0.001 USDC or 1000 drops XRP) is unique behavioral information not present in annotations. This goes beyond the baseline and gives the agent key operational details.

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 concise, front-loaded with the core purpose, and each sentence serves a distinct role: return description, usage context, alternative routing, and cost/behavior. There is zero filler and the structure leads with the main function, making it efficient for quick scanning.

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 simplicity (one optional parameter), the presence of an output schema, and comprehensive annotations, the description covers all necessary aspects: what it returns, when to use it, how it differs from siblings, and its side-effect-free nature. No critical operational detail 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% and the parameter 'framework' is fully described in the schema: 'Optional. One of langchain, llamaindex, ollama, or xrpl. Omit to list every known deprecation.' The description's phrase 'for one framework or all four at once' adds no new meaning beyond the schema, 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?

The description clearly states the action ('Return'), the resource ('known-deprecated API catalog'), the fields (id, old API, replacement, fix), and the scope (one framework or all four). It explicitly differentiates from sibling tools by noting it works 'without a stack trace or source snippet' and names alternative tools for error logs and code review, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use when you want the full deprecation list without a stack trace or source snippet.' It further specifies alternatives: 'Prefer diagnose_framework_error when you have an error_log and review_framework_code when you have code.' This clearly routes the agent based on available context, leaving no inference required.

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 provide readOnlyHint=true, openWorldHint=false, and idempotentHint=true, and the description adds useful non-obvious traits: it is free per call with no x402, catalog-backed, and has a scoped list behavior rather than a search or deprecation dump. There is 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 compact and front-loaded with the core listing action, followed by a clear usage trigger, cost note, and sibling exclusions. Every sentence earns its place without redundancy.

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 parameterless list tool with a rich output schema and safety annotations, the description covers what is returned, when to use it, and what it is not. Nothing an agent needs to invoke 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?

The tool has zero parameters, so parameter risk is trivial and the empty schema is fully covered. The description still adds value by listing the framework IDs and explaining they are string values to pass elsewhere, though no current parameter needs documentation.

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: 'List the framework ids this server covers' and enumerates the exact IDs and returned attributes. It explicitly distinguishes itself from sibling search_ai_framework_docs and list_known_deprecations, so an agent can identify the correct tool without opening schemas.

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

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

It gives an explicit trigger condition: 'Use when you do not know which framework string to pass.' It also names what this tool is not, referencing the sibling tools to use instead, leaving no ambiguity about when to choose 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 read-only and idempotent behavior. The description adds non-obvious context beyond annotations: the call is paid ($0.001 USDC or 1000 drops XRP) and catalog-backed. This informs cost expectations and data source. Not-found behavior is not covered, but this is minor for a simple lookup.

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 focused sentences front-load the core operation, then give the use condition, alternative tools, and cost. Every sentence earns its place with no repetition of schema content.

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 a complete input schema, rich parameter descriptions, an output schema, and helpful annotations, the description covers purpose, use case, alternatives, and cost. An agent has enough to decide when to invoke it and how to invoke 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 coverage is 100%, and both parameters already have meaningful descriptions: symbol is 'API name or import path' with examples, and framework is defined with accepted library names. The description adds output-shape context, but it does not need to compensate for schema gaps.

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 precise operation: 'Map an API name to the current package, install line, import, and call shape.' It gives concrete examples and distinguishes the tool from siblings by framing it as resolving symbols whose location is unknown.

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 says when to use this tool — 'when you know the symbol but not where it lives' — and names alternatives with their preferred contexts: search_ai_framework_docs for concepts and fetch_latest_syntax for topic snippets. This gives clear routing 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 provide readOnlyHint=true and idempotentHint=true. The description adds essential context beyond these: it explicitly states 'Does not execute or submit' (confirming read-only behavior), discloses a per-call cost ($0.001 USDC or 1000 drops XRP), and asserts 'catalog-backed, not LLM-invented' for reliability. All of this is valuable and non-redundant; there is no contradiction with the annotations.

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

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

The description is compact and well-structured. The main purpose and output are front-loaded in the first sentence. Usage guidance, safety note, and cost follow logically. Every sentence earns its place; 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 moderately complex with 3 parameters and an output schema that already describes return structure. The description covers the core decision points: what it does, when to use it, that it is read-only, cost, and reliability. It appropriately routes to the main sibling tool. No missing information that an agent would need 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?

The schema covers all 3 parameters with descriptions, so the baseline is 3. The description adds meaningful semantic value: it lists concrete dead API examples (LLMChain, initialize_agent, ServiceContext, ripple-lib) to guide the framework choice, and clarifies that 'code' is 'Source to lint before running' and explicitly 'Not a stack trace (use diagnose_framework_error)'. This goes beyond the schema's brief descriptions without being exhaustive.

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 exactly what the tool does: scans source against known dead APIs and returns each hit with a replacement and a unified-diff hunk. It is specific about the resource (source), the action (scan), and the output. It also differentiates from the sibling diagnose_framework_error by clarifying the timing of use (before running code vs. after a stack trace).

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 says 'Use before running agent-written code' and points to the alternative: 'diagnose_framework_error is for after a stack trace.' This gives clear when-to-use and when-not-to-use guidance, and even names the specific sibling tool for the other scenario. No ambiguity remains.

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?

Adds meaningful behavior beyond the readOnly/idempotent annotations: it does not execute or submit, it returns a patched file plus full diff, unsafe transforms stay for a human/agent, and it discloses the per-call cost. 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?

Four sentences deliver purpose, usage, limitations, side-effect safety, and cost with little waste. The 'Leftover lists unsafe call-site transforms' sentence is awkward and slightly ambiguous, so it is not perfectly structured.

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 and strong annotations present, the description covers the key operating constraints: when to use, what is left unchanged, non-execution, and cost. The ambiguity around 'Leftover lists...' is a minor completeness gap, but nothing critical 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 description coverage is 100% and each parameter already has a clear schema description. The description adds some context about rewrite scope and output, but it does not materially extend parameter-level meaning beyond the schema.

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

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

Description states a specific verb and resource: apply conservative catalog rewrites (imports/identifiers) to a snippet and return a patched file plus unified diff. It also distinguishes the tool from review_framework_code and other siblings by explaining the output and 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?

Explicitly says to use when review_framework_code found hits and an applyable file is wanted, and notes that unsafe call-site transforms remain for a human/agent. It lacks an explicit 'do not use when' or named alternative for the leftover cases, but the trigger condition is clear.

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

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

The annotations already mark readOnlyHint, idempotentHint, and openWorldHint=false, and the description reinforces and extends this: it is a local index search, never live-crawls, returns compact chunks, and uses hitCount 0 to signal no match. It also discloses the per-call cost, adding practical behavioral context beyond annotations.

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

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

The description is compact and front-loaded with the tool's essential behavior, then covers usage boundaries, common failure recovery, and cost. Every sentence earns its place; there is no filler or repetition of schema content.

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 search tool with a rich output schema and detailed parameter documentation, the description covers what it searches, how it behaves, when to use it, which siblings to prefer instead, and cost. No practical gap remains for an agent deciding whether 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 coverage is 100% and the schema already documents both parameters well. The description adds extra value by framing queries as 'concepts, symbols, or questions' and by advising to shorten the query when hitCount is 0, which helps the agent craft an effective query parameter.

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 ('search'), a precise resource ('local Markdown index for langchain, llamaindex, ollama, or xrpl'), and disambiguating traits ('returns compact chunks and never live-crawls'). This clearly distinguishes it from siblings like diagnose_framework_error, resolve_symbol, and fetch_latest_syntax.

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 says when to use it ('concepts, symbols, or questions') and when not to, naming the exact sibling alternatives for stack traces, import/package lookup, and current syntax. It also gives a concrete recovery action when no results are found: shorten the query.

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