Databricks Field Guide by TechFabric

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds the interaction model the annotations can't: one question per call, options passed as numbers-so-far to advance state, and a form:true variant for elicitation-capable terminals. It does not say what happens with invalid or out-of-range choices, which is a minor gap.

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

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

The core purpose is front-loaded, but the prose is overstuffed: the five decision ids appear in the first sentence and the same intent is re-expressed as three example questions, and the form:true sentence repeats the schema description almost verbatim. The long parenthetical and multi-clause sentences make it slower to parse than needed.

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 and rich annotations, the description supplies what remains: the ask-answer loop, the decision-id vocabulary, and the interactive form variant. Only edge behavior (invalid choice numbers, exceeding maxItems) is left 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 coverage is 100%, so baseline is 3; the description still adds meaning by framing 'choices' as option numbers accumulated from the first question rather than a fresh set, and by clarifying that omitting 'question' yields the list. The form flag's purpose is restated with the terminal condition, though it largely duplicates the 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 and resource ('walks a Databricks decision one question at a time') and enumerates the five decision trees it covers (which-compute, serverless-or-classic, lakebase-or-delta, genie-or-dashboard, streaming-or-batch). The 'every answer rests on the guide's own sentences, verbatim, with the section to read' clause distinguishes it from exploratory siblings like search_guide or explore_concept.

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 triggers as quoted user phrasings ('should I use serverless or classic', 'Lakebase or Delta?', 'which compute for this job'), which is strong positive guidance. It also notes 'Omit it for the list' for the question param. It does not name a competing sibling or state when NOT to use it, so it falls short of a full when/when-not/alternatives statement.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavioral context the annotations cannot: results come back as a range with assumptions, every number carries source sentence, section URL, date and cited pricing page, and unknowns are surfaced under 'gaps' rather than fabricated — meaningful for trusting the output.

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

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

The purpose is front-loaded in the opening clause and the second sentence covers the gap-handling policy. It is dense but each clause (sourcing, provenance, gaps, unit_prices) carries distinct information; only the long comma-laden enumeration of pricing categories borders on run-on.

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 22 parameters, an output schema, and strong annotations, the description supplies what the structured fields do not: provenance guarantees, range-with-assumptions output shape, and explicit no-guessing behavior for unlisted shapes. It does not spell out defaulting behavior for hours/days, but the schema covers those.

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 91% with rich per-parameter documents including enums and defaults, so baseline 3 applies. The description adds no parameter-level semantics; the terms it names ('unit_prices', 'gaps') look like output fields, not inputs, so it does not compensate beyond what the schema already provides.

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 ('Estimate a Databricks workload's monthly cost') and enumerates the exact figure families it draws on (DBU list prices, model serving rates, storage, the Lakebase floor). Nothing among the learning-oriented siblings overlaps, so an agent can tell immediately this is the only cost tool.

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 implicitly defines the use case (estimating monthly cost) and specifies a fallback input path when the guide lacks a figure ('a serverless job, an instance type it does not list' → supply dbus_per_hour). However, it never states when NOT to use it or names an alternative among siblings, and sibling tools are unrelated, so routing guidance is only implied.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, yet the description still adds real context: not affiliated with Databricks, no copyrighted exam questions reproduced, and coverage reported with gaps acknowledged. It doesn't describe the multi-call flow (list → domain → step) that governs behavior.

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

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

The core intent is front-loaded, but it is delivered as one very long run-on sentence with a nested parenthetical that re-lists all eight exam slugs already covered by the schema. The trigger examples are useful; the duplicated slug inventory is not.

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 and annotations covering safety, the remaining burden is the interaction model, which is mostly conveyed via the per-domain deliverable list and the disclaimers. It is only slightly short on how `step`, `done`, and `domain` compose across calls.

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 are already documented, including `done` and `step`. The description adds only the omit-`exam`-for-list convention and that `domain` selects practice questions; it never mentions the `step`/`done` progression, so it stays at the baseline.

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

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

States a concrete resource (Databricks certification prep) and enumerates exactly what a call returns: per-domain weights, guide sections/concepts, coverage honesty, official links, and practice questions for one domain. It implicitly differentiates itself from quiz_me/flashcards by being the whole-exam prep surface, but never names a sibling 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?

Gives verbatim user triggers ("help me prepare for the Data Engineer Associate", "quiz me for the exam") and notes that omitting `exam` returns the list, so the entry point is clear. It offers no exclusions, and the "quiz me" phrasing overlaps with the quiz_me sibling without 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?

The description adds substantial behavioral detail beyond the annotations: every point includes the guide's own sentence and section URL, results carry a worked example and interactive-model data, assumptions are separated from guide statements, and MCP Apps rendering is described. It also explains what happens when no concept is provided or the concept is unknown.

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

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

The purpose and triggering guidance are front-loaded, and most clauses carry useful information for a tool with multiple modes. However, the single dense paragraph is long and repeats the concept list that also appears in the schema, making it less scannable than it could be.

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 annotations, full schema coverage, and output schema, the description is complete: it covers purpose, when to call, output shape, interactive rendering, concept fallback, and the separation of guide facts from model assumptions. An agent has enough context to invoke it correctly without opening the schema.

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 five optional parameters, including concept, form, exam, step, and done. The description reinforces concept naming and the no-concept list behavior, but does not add much beyond the schema.

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

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

The description states a specific verb and resource: it explains one Databricks concept step by step from the Field Guide's chapters, with a concrete list of supported concepts. It distinguishes the tool from answering from memory or running code, but does not explicitly differentiate it from sibling tools such as explore_diagram or get_chapter.

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 triggering guidance: call it first when the user asks conceptual how-to questions like how the Delta transaction log works or to show watermarks step by step. It also states the fallback for unknown or missing concepts, though it does not name sibling tools as alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds what the payload actually contains (every diagram's nodes, its edges in order, and the Mermaid source) and that nodes cross-link to chapter sections. That is genuine value beyond structured fields. It leaves slightly unclear how the 'step by step' playback is driven (repeated calls vs. a single listing), which keeps it from a 5.

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

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

Three sentences, front-loaded with the core purpose before examples and payload details. The colon-chained clauses are dense but every sentence contributes (purpose, trigger, output content). Minor redundancy between "played step by step" and "each ... in order".

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 enumerate return values, and both parameters are fully documented in the schema. What it provides — intent matching, traversal semantics, and a note that the text is terminal-renderable — is enough to call the tool correctly. Only the interaction model for 'step by step' remains underspecified.

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%, including the slug/path/URL forms for `chapter` and the anchor-or-heading meaning of `section`, so the schema carries the burden. The description adds only indirect framing ("a chapter's own diagrams") and says nothing extra about how `section` narrows the result set. 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 — plays a chapter's diagrams step by step, walking edges/messages in order and linking nodes to chapter sections. This is clearly distinct from a generic visualization tool because it is scoped to a single chapter's own diagrams and describes the traversal semantics. It never names a sibling (e.g. `visualize` or `explore_concept`) to sharpen the boundary, so it stops short of a 5.

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

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

It gives explicit trigger utterances ("show me the diagram for Lakebase branching", "walk me through the medallion diagram"), which is strong positive guidance for an agent matching user intent. There is no when-not-to-use clause and no named alternative for cases where the user wants a diagram outside the chapter or an interactive drawing rather than a step listing.

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 read-only, idempotent, non-destructive, closed-world behavior, yet the description adds genuine context: generation is deterministic from the guide, card backs carry the guide's own sentence plus section URL, an uncovered domain returns an explicit 'not covered' message, and hosts rendering MCP Apps support Got it / Not yet tracking with resume codes. It never states size limits or latency, but the deck-size and interaction model are well disclosed.

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

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

Front-loaded with the core purpose and the mode list, and every sentence carries information. The eight-item parenthetical enumeration of exam IDs duplicates the schema's own enum text verbatim, which is wasted space in a description.

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

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

An output schema exists, so return values need no explaining; the description covers all four invocation modes (exam+domain, chapter, resume, plan-derived done), the deterministic sourcing, and the fallback when a domain is uncovered. 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%, so the baseline is 3; the description earns above that by explaining the conditional pairing of exam + domain, that done is the exam_prep plan's completed steps so the deck can report its step and route Next back to the plan, and that a resume code names its own domain or chapter so nothing else is needed.

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 — interactive flashcards built deterministically from the Field Guide for an exam domain or chapter — and describes what each card contains (glossary terms, FAQs, mapped section lead sentences). It does not explicitly distinguish itself from the sibling quiz_me, which is the nearest alternative, so it stops short of a 5.

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

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

Gives concrete trigger phrasing ('flashcards for the Data Engineer Associate's governance domain', 'drill me on Unity Catalog terms') and a clear rule for the resume mode ('send it back as resume, alone'). It says when to call but never states when not to, or how it differs from quiz_me for the same domain.

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 safety is fully covered structurally. The description adds useful content-shape detail (code blocks, FAQs, last-changed, cited links) but says nothing about failure behavior when a slug or section is unknown, so it adds moderate rather than rich context.

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

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

It is a single dense sentence stacked with parentheticals ('or margin note', 'or one section of it' followed by five parallel clauses), which makes the two modes harder to parse than they need to be. There is no wasted marketing language, but restructuring into an explicit whole-chapter vs section split would earn more.

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 needn't enumerate return values, and with rich annotations and fully documented parameters it covers both invocation modes adequately. The only genuine gap is guidance on what happens for an unknown slug or section.

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 goes beyond it by explaining the two operating modes: without a section you get the whole chapter as Markdown, with a section you get an outline, separately listed code blocks, FAQs and links, which genuinely sharpens how 'section' should be used.

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 the resource (a chapter, margin note, or a single section of the guide) and the output shape (clean Markdown, code blocks intact), so an agent can tell this is a read-a-chapter tool. It does not explicitly contrast itself with search_guide or list_chapters in the text, which keeps it short of 5.

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

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

Usage is only implied: you pass a slug or path and optionally a section to get content back. The description never states when to reach for this versus search_guide (discovery) or list_chapters (enumeration), and the only pointer to those siblings lives in the schema, not the description.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds one genuine piece of context beyond structured fields: that returned syntax may be stale and the cited doc links should be checked, plus a note that results carry the surrounding explanation and source anchor.

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 returned artifact and its composition; the caveat sentence is short and earns its place. Slightly dense in the first sentence but 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 and annotations carry the return shape and safety profile, and the description supplies purpose plus the staleness caveat. The main remaining gap is sibling differentiation, which matters given nearby search_guide and get_chapter.

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; however the description adds meaning beyond the schema by noting results are scoped to 'a topic' and include the section URL and cited docs links, clarifying that filtering is topical and provenance is returned. It still says nothing about lang, limit, or chapter usage.

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

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

States a concrete resource (code blocks: SQL, Python, CLI, config) filtered by topic, plus what accompanies each block. It doesn't name a sibling to differentiate from, so the agent must infer how it differs from search_guide or get_chapter.

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?

'Runnable context for a coding agent' implies the use case (wanting usable code rather than prose) but gives no explicit when-to-use/when-not rules and never points to search_guide or get_chapter as alternatives.

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

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

Beyond the read-only and idempotent annotations, the description discloses that progress is client-side ('progress lives with the reader: send the steps done back as done') and that MCP Apps hosts render a map while the text remains complete. These are meaningful behavioral details an agent would not get from annotations alone.

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

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

The purpose is front-loaded, and the later sentences each carry distinct information about triggers, progress, rendering, and the no-path case. The opening sentence is dense with nested parentheticals, but overall the description is appropriately sized and has little waste.

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 two-parameter tool with an output schema and full schema description coverage, the description covers purpose, trigger conditions, return structure, progress handling, and rendering fallback. An agent has everything needed to select and 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%, so the baseline is 3, but the description adds useful semantics: the path values are enumerated and 'No path: the list' clarifies omission behavior. It also reinforces that 'done' comes from an earlier result and belongs to the reader rather than the server.

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: a curated learning path through the Field Guide, with named paths and a clear breakdown of the returned steps. It distinguishes itself from siblings like list_chapters and explore_concept by describing ordered steps that each include the call that opens them.

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

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

It gives explicit trigger phrases such as 'where do I start with Databricks' and 'a learning path for an analytics engineer', plus the 'what should I learn next' case. It does not name sibling alternatives like start_here or exam_prep to clarify when not to use this tool, so it falls just short of full 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral detail that results are returned in guide order and that margin notes are included, but says nothing about size, pagination, or completeness of the payload.

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?

A single front-loaded sentence that leads with scope ('Every chapter') before enumerating returned fields. The field list is dense but each item earns its place by telling the agent what to expect back.

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 document return values, and with no parameters there are no inputs to explain. What remains missing is only usage context relative to the sibling tools, not any information required 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The schema is empty and additionalProperties=false, which the description correctly does not contradict.

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 (list chapters) and scopes it as 'Every chapter ... in the guide's order', which implicitly contrasts with the singular sibling get_chapter. It never names that sibling, so differentiation is inferred rather than explicit.

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 no when-to-use guidance, no exclusions, and no reference to alternatives such as get_chapter or search_guide. The agent must infer that this is the enumeration entry point from the word 'Every' alone.

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 substantive behavior: questions are built deterministically and no model writes them, each item ships with its answer, explanation and section URL, and the second call with the same chapter/section plus answers performs scoring. Mode-specific behavior (view rendering vs elicitation vs text) and the resume-code recovery path are all disclosed.

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

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

A single long paragraph, but front-loaded with the trigger phrasings before the mechanics, and nearly every clause carries decision-relevant information (determinism, fallback mode, re-call for scoring, resume). It is dense and could be split into short mode-specific sentences for faster 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?

For a seven-parameter interactive tool with an output schema, the description covers generation source, the three delivery modes, the two-call scoring flow, and the resume-code path. Nothing an agent needs in order to invoke and follow up 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, and the description earns above that by explaining interaction semantics the schema cannot: answers must be sent with the same chapter and section as the quiz that was asked, form should only be set when the reader wants forms and otherwise the result is unanswered, and resume alone carries its own chapter or domain.

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 (quizzes the reader) and pins down exactly what is produced: five to eight multiple-choice questions on a chapter, a section, or the whole Field Guide, assembled deterministically from the guide's own tables, FAQs and glossary. The example utterances ("quiz me on Unity Catalog", "test me on Lakebase") make the trigger unambiguous and separate it from siblings like explore_concept or get_chapter.

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 invocation phrasings and then routes by environment: answers and scoring happen in the MCP Apps view, via elicitation forms when form: true, or as a text list the agent must walk through and then re-call with answers to score. It never contrasts itself with the closest siblings (flashcards, exam_prep), leaving the agent to infer which to pick — the only real gap.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses determinism, that no model is invoked, the exact shape of each finding (line, why, fix, verbatim guide passage with section URL, docs links), and that sections worth reading are also returned. The one-file-per-call constraint is a real behavioral limit an agent must plan around.

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 verb, the input types and the deterministic standard, then the output shape. The long enumeration of rule categories is informative but borders on a run-on sentence; it earns most of its length but could be tightened.

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 3-parameter, fully-described, read-only tool with an output schema, this covers everything an agent needs: what it accepts, what it returns, that it is deterministic, and the one-file scope. Nothing material is left to inference.

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 meaning by spelling out what counts as 'code' (SQL, PySpark or notebook source, DAB/job/cluster/warehouse YAML), which clarifies the accepted inputs beyond the terse schema text. It does not repeat the 48000-character limit or lang-omit behavior, which stay 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?

States a specific verb and resource ('Check one file of SQL, Python ... or YAML') and the exact standard applied ('the Field Guide's own best-practice rules, deterministically'). It enumerates the concrete classes of violations, so an agent can tell it apart from siblings like search_guide or get_chapter 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?

'One file per call' and 'No model is called: weigh the findings yourself' give clear operating context and a post-processing instruction. It does not explicitly name a sibling alternative or an exclusion (e.g. when to prefer search_guide for prose lookup), so it stops short of full 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 declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower. The description still adds real value by disclosing result ordering ('best sections first') and the shape of each hit (snippet, anchored URL, last-changed date).

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, front-loaded with what is searched, followed by what comes back, followed by the next action. No filler or repetition of the title.

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 3-parameter read-only search with a full schema, annotations, and an output schema, the description covers purpose, result shape, and the follow-up path to get_chapter. 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%, so the schema already documents query, kind, and limit with an example and defaults; baseline 3 applies. The description adds only the implicit note that results are relevance-ranked, nothing about the kind filter or limit semantics.

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) and resource (the guide's chapters, margin notes, events) plus the domain constraint (a Databricks question). It also names the sibling handoff (get_chapter) so an agent can distinguish searching from reading.

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?

Makes the trigger clear — searching for a Databricks question — and explicitly routes the follow-up step to get_chapter with the URL or slug+anchor. It does not say when to prefer list_chapters or explore_concept instead, so exclusions are absent.

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 read-only, idempotent, non-destructive and closed-world, and the description adds genuinely new facts: no sign-in, no workspace access, no saved personal data, plus host-dependent presentation (interactive card under an MCP Apps host vs. one question at a time in a terminal). That is behavioral context an agent cannot obtain from 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?

Information is front-loaded with the imperative and the trigger phrases, and every sentence carries routing or constraint value. It is dense — several ideas are compressed into each sentence — but nothing is redundant with the schema or annotations.

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 no explanation; the description instead covers the variables that matter for correct invocation: mode selection from zero args, topic, or exam, host-dependent UX, and the absence of auth or setup requirements. 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 coverage is 100%, so the baseline is 3, but the description adds routing semantics tying parameters together: no arguments means a Unity Catalog diagnostic, a topic opens its concept or chapter quiz, and goal=certification with an exam opens that domain's practice and flashcards. It also signals that exam implies certification, reinforcing the schema's own note.

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 this is an entry point to a Databricks learning Field Guide and enumerates what each mode starts (Unity Catalog diagnostic, concept or chapter quiz, certification practice with flashcards). It distinguishes itself from the Databricks development plugin, though it never names the closely related siblings (exam_prep, quiz_me, explore_concept, flashcards) it routes into.

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 trigger phrases ('help me learn Databricks', 'try the Field Guide', certification prep) tell the agent exactly when to prefer this tool, and 'not a replacement for the Databricks development plugin' gives a when-not boundary. The guidance is strong but stops short of naming which sibling to call instead once inside a specific task.

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 carried by structured data. The description does add real context the annotations cannot: output fidelity ('with the extension's own code, so the output matches it') and the no-workspace execution guarantee. It says nothing about output shape, limits, or error behavior, so the value added is modest against already-strong 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 mid-section is a single ~110-word comma-separated enumeration of generator categories that duplicates (and does not match) the enum already in the schema. It is front-loaded correctly, but the bulk of the text does not earn its place and actively omits the mapping an agent would need.

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. However, for a tool with a 33-value enum and a free-form nested `inputs` object, the description never explains how to translate an intended task into a specific enum id or which inputs a given generator requires — it only points the agent at the discovery call. Adequate as a pointer, incomplete as guidance for a tool this broad.

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 carry their own descriptions in the schema, so the baseline applies. The description contributes no syntax or format guidance for `inputs` beyond echoing the omit-to-list behavior. Worse, the human-readable generator list in the prose does not map to the enum ids (e.g. 'Unity Catalog grants' vs `uc-perms`), so it does not help the agent populate the enum correctly.

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

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

The opening sentence states a specific verb and resource (runs an offline generator from the Build tab of the TechFabric Chrome extension) and the trailing sentence clarifies scope ('Text only: nothing runs against a workspace'). It is clear what the tool does, but the 30-plus-item comma list that follows muddles the core purpose rather than sharpening it, and no sibling (e.g. toolkit_info) is contrasted.

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 'Omit generator for the list and each one's inputs', which gives the agent a concrete discovery call pattern, and the closing line establishes a boundary (nothing runs against a workspace, no model is called). It stops short of naming alternatives such as toolkit_info or review_databricks_code, so routing is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorldHint=false, so 'Read-only and deterministic' mostly restates them. The description does add useful non-schema context – coverage of permissions, privacy model, and per-feature workspace requirements – but since an output schema exists, its sentence describing what each feature entry contains is largely redundant with structured 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?

Front-loaded with the purpose and the call triggers in the first two sentences, with the feature/routing detail after. The first sentence is dense with parentheticals (product name, version) that could be trimmed, but overall it earns its space.

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 agent knows it is a read-only lookup tool for extension documentation, how to trigger it, and that it covers install, permissions and privacy, with an output schema covering return shape. The main remaining gap is that it doesn't clarify the relationship between the two optional parameters (e.g., what happens when both or neither are supplied).

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 (feature enum and question, max 300 chars) are already documented in the schema. The description's example questions loosely illustrate the 'question' parameter but add no syntax or format detail beyond what the schema provides; 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?

Opens with a specific verb+resource: it explains what TechFabric's Chrome extension for Databricks does, how to install it, its permissions and its privacy model. It also distinguishes itself from siblings by naming the server-side tools (toolkit_generate, estimate_cost, review_databricks_code, explore_concept) whose functionality overlaps with extension features.

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 trigger phrasing: 'Call it for "what can the TechFabric Chrome extension do", "does the toolkit support X", "how do I install it" or "what permissions does it need"'. It also routes the agent between this tool and the server tool equivalents, which is exactly the when-to-use guidance an agent needs.

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 say readOnly/idempotent/non-destructive, and the description adds substantively: nothing is stored, no model is called, the tool validates structure not facts, and a bad document returns the spec's VALIDATION_FAILED list to fix. It also discloses rendering differences between MCP Apps hosts and plain text, the 'Composed by your assistant' labelling, and that only Field Guide pages are accepted as sources — all consistent with openWorldHint=false.

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

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

The core purpose and the trigger list are front-loaded in the first two sentences, and almost every clause carries information an agent needs. However it is a single dense paragraph that chains card types, trigger phrases, sibling routing, Databricks sourcing rules, host rendering, and validation behavior — it would be more scannable as short labelled sections.

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 rich annotation set, 100% schema coverage, and an output schema, the description covers everything the schema can't: when to pick it, what it does not do, prerequisite sourcing for Databricks questions, host-dependent rendering, and failure behavior. An agent has no open questions before calling 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%, so the parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the most consequential constraint (sources must be Field Guide URLs, non-guide links are listed as not-from-the-guide) but adds no format or syntax detail for `document` or `title` 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?

Starts with a specific verb and resource ('draws your answer as a card') and enumerates the concrete card shapes it produces (comparison with verdict, plan steps, calculator with sliders, quiz, table, Mermaid diagram). It also names the sibling tools it is not (explore_concept, decide, estimate_cost), so an agent can distinguish it without opening a 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 trigger vocabulary ('compare', 'X vs Y', 'pros and cons', 'roadmap', 'show me', 'chart') plus a negative rule: don't answer with a long Markdown table or list. It also routes competing intents away by name ('a decision decide has a tree for, and a cost estimate_cost prices go to those tools first'), and gives a Databricks-specific prerequisite sequence (search_guide/get_chapter first, then cite URLs).

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, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: ordering (newest first), content categories (margin notes, release-stage changes, updated chapters), and the default time window. It does not cover pagination or limit behavior, but it goes beyond 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 two sentences, front-loaded with the core scope ('Recent Databricks changes the guide tracks, newest first') and then efficiently enumerates content types and the default window. 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 simple read-only tool with a full output schema and 100% parameter description coverage, the description supplies ample context about what is returned, how it is ordered, and default behavior. No critical information 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%, so the schema already documents both parameters and their defaults. The description restates the default 30-day window but adds no new syntax or format details beyond what the schema provides.

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 retrieval purpose: recent Databricks changes tracked by the guide, newest first, including margin notes, release-stage changes, and chapter updates. This clearly distinguishes it from siblings that fetch individual chapters, code examples, or perform searches.

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

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

Usage is implied by the content description ('Recent Databricks changes'), and the default 30-day window is stated. However, there is no explicit guidance on when to choose this over alternatives like search_guide or list_chapters, nor any exclusions.

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