TechFabric

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

Annotations already flag destructive=true and idempotent=false, so the safety profile is covered; the description still adds real context: the auth scope, that edits are persisted immediately like update_draft, that rule-based checks run synchronously while a full check runs in the background, and that publishing is out of scope. It could go further on whether the apply is reversible, which matters given destructiveHint=true.

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 auth requirement and the core constraint are front-loaded, and every sentence carries operational information. The long compound sentence covering save semantics plus background checks is heavy but not wasted.

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?

A mutating, destructive tool with rich annotations and an output schema: the description still covers auth, side effects, timing of checks, and the publish boundary. Nothing an agent needs before invoking it 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 explains id, proposal_id, accept, and reject. The description only ties proposal_id back to propose_edits and clarifies that accept reflects the engineer's decision; that's marginal but not redundant, so the baseline 3 holds.

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 action (apply accepted proposal changes to the saved draft text) and names the source tool (propose_edits) plus the comparable sibling (update_draft saves). An agent can distinguish it from propose_edits, update_draft, and publish_draft 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?

Gives the explicit precondition (a TechFabric engineer's Microsoft sign-in with scope blog.write) and the key constraint: only changes the engineer accepted, never the agent's own choice. It also names the boundary against publish_draft ("Never publishes"), so the when-not is stated, not 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?

Goes well beyond the annotations: declares the Microsoft sign-in prerequisite and blog.write scope, explains that the answer is persisted as a draft source read by fact-check, and distinguishes chat-mode from form-mode behavior. This explains why readOnlyHint=false and idempotentHint=false without contradicting them.

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?

One dense paragraph whose sentences all carry load — auth, constraint, return path, persistence, prohibition — but the nested parentheticals and the opening auth detail ahead of the core purpose make it slightly harder to scan than it needs to 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?

For a 5-parameter, non-idempotent tool with an output schema, the description covers what the schema cannot: the auth prerequisite, the two-call interaction loop, and where the answer lands. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by explaining the form/chat branch and that the answer must be recorded "word for word." It does not discuss passage or id semantics beyond what the schema already says.

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?

"One question only the engineer can answer... returned for you to ask in chat" states a specific verb (ask), a specific resource (the author/engineer), and the scope constraint that separates it from generic search or draft tools. The parenthetical examples (what was measured, who it was for, what happened) make the intent 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?

Clear triggering context (only questions the engineer alone can answer) plus an explicit prohibition: "Never answer it yourself." It also explains the two-step flow — call again with their answer — but names no sibling tool as an alternative, so routing versus check_draft or quiz_me is left to inference.

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

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

Beyond the readOnly/idempotent annotations, it discloses the privacy contract ("answers are scored and never stored or logged") and the side effect of contact:true (opens /contact via URL elicitation for confirmation). It also explains the multi-step interaction protocol — first call returns questions, later call scores answers.

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

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

The purpose is front-loaded, but the body is a single sprawling colon-and-semicolon-chained paragraph with nested conditions that are hard to parse on one read. The information is dense and mostly earns its place, yet it would benefit from being broken into distinct sentences or bullets.

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 covering the readout and full annotation and parameter coverage, the description supplies what structured fields can't: the question/answer round-trip, privacy handling, and client-mode branching. Only minor gaps remain, such as how the five scored areas are ordered in the response.

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 all three parameters are already documented, and the description largely restates the same branching logic (form, answers, contact). It does clarify sequencing ("call it without answers for the questions"), but adds little meaning the schema doesn't already carry — baseline 3.

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+resource — a Databricks readiness and migration check — and details its mechanics (eight multiple-choice questions, fixed-point scoring into five areas, a readout with starting points and links). It is clearly distinguishable from siblings such as quiz_me or search.

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 concrete invocation branches: call with no answers to get the questions, form:true for form-capable clients, MCP Apps hosts score in-view, otherwise ask in chat and send answers. Example reader phrasings ("are we ready for Databricks", "assess our migration readiness") anchor the trigger. It doesn't state when NOT to use it or name a sibling alternative, so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint false, idempotent, non-destructive), the description discloses an auth prerequisite (Microsoft sign-in, scope blog.write), run time (~a minute) with a 25-second wait-then-progress pattern, that work is idempotent ("nothing runs twice"), task-extension behavior, and a wait after submit_draft. The first_hand confirmation flow is also spelled out, including that the engineer, not the agent, confirms.

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

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

The content is dense but nearly every clause carries operational information, and the most important constraints (auth, sequencing, polling) come early. The telegraphic fragments and stacked colons ("The final verification publish_draft needs.", "never to iterate.") make it slower to parse than it needs to 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?

For a 12-parameter tool with an output schema and annotations, the description covers the workflow position, timing, idempotency, and confirmation mechanics that an agent cannot infer. Remaining gaps are minor and mostly covered elsewhere: specific failure modes and what the check result body contains are left to the output 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 coverage is 92%, so the baseline is 3, and the description earns an upgrade by explaining the id vs no-id fork and the interplay between first_hand_to_confirm and the first_hand parameter. It does not, however, add much about kind, images, sources, or wait_seconds beyond what their schema strings already say.

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 full checks on your saved draft (judge, slop classifier, fact-check)" names the verb (check), the resource (a saved draft), and the three checks performed. It explicitly distinguishes itself from siblings: it is what "publish_draft needs" and must be run "after lint_draft passes," and it does a different, non-publishing check when called "without id."

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?

Sequencing and exclusions are explicit: run it after lint_draft passes, "never to iterate," and note that a no-id markdown check does not count toward publish_draft. It also states the polling contract (call again, never two at once) and what to do on next_action confirm, so the agent knows both when to call it and how to call it again.

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/idempotent/non-destructive; the description adds real context beyond them — Microsoft sign-in with blog.write scope, ~1ms latency, free, the iterate-until-ready loop, and the human approval gate before drafting. Auth scope and the human gate are the most valuable additions.

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

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

Dense but largely front-loaded and purposeful; each clause (auth, cost, rules checked, iteration, approval gate) contributes something. The semicolon-heavy single paragraph is slightly hard to parse but not padded.

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

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

With an output schema present, return values needn't be explained, and the description still tells the agent auth needs, cost/latency, what is validated, and the follow-up workflow. Complete enough for a 10-parameter validator, with only sibling disambiguation 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 90%, so the baseline is 3. The description reinforces a few semantics (opening's device compared against the last ten published posts, case-study section shape), but most parameter meaning is already carried by the schema's own 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 states a specific action: validating an outline (titles, opening, sections, diagram, FAQs) against the title/opening/heading/FAQ rules before prose is written. It even enumerates what an outline contains and how a case study differs. It does not name siblings like check_draft or lint_draft, so it falls short of a 5.

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

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

Clear workflow guidance: run it on the outline, 'Fix what it finds and call again until ready', then show outline_markdown and draft only after the engineer's OK, with the unattended flag changing that gate. There is no explicit comparison against alternative validation tools, so it is not a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description still adds real behavioral context: only excerpts are returned ("the bold statement and the start of each section"), fields appear only "where the case study states them", and "nothing is added that the case studies don't publish" — an explicit no-fabrication guarantee. It doesn't cover failure modes for an unmatched slug or what the interactive surface does on selection.

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 what the tool produces, then input modes, then example utterances — a sensible order. The middle section is a dense colon-chained run-on that takes a second pass to parse, though almost every clause carries distinct information.

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

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

With an output schema and full annotation coverage, the description's job is mainly input modes and fidelity limits, both well covered. Minor gap: no statement of what happens when a named case study isn't found or when fewer than two 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 coverage is 100%, so the baseline is 3, but the description goes further: it explains that `case_studies` accepts a slug, a URL, or title words (broader than the schema's bare string array) and that `topic` is a mutually exclusive alternative that returns "the closest three" rather than exact matches. Omission semantics ("leave out for the list") are also stated.

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?

Names a specific verb+resource (compare two or three published case studies side by side) and enumerates exactly what gets returned: challenge, strategy, solution, results, client, sector, stack, and per-section links. No sibling tool does case-study comparison, so an agent can route here unambiguously from the name plus this sentence.

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?

Covers all three input modes explicitly — slugs/URLs, a topic for the closest three, or neither to get the choosable list — and supplies trigger phrasing ("compare your case studies", "show me your Databricks projects side by side"). It stops short of naming when NOT to use it (e.g., vs. `search` or `explore_post` for single-item lookups).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: the diagram becomes click-through steps, pages without a diagram fall back to section stepping, topic input resolves to the closest post, and the text output is complete without an MCP Apps host. It doesn't mention limits on which posts are explorable or how much of the section body is 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?

Front-loads the core definition, then host behavior, then example phrasings, in that order. Despite covering several topics the prose is dense and every clause carries information; nothing is repeated from the title or schema.

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

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

With an output schema present, return values need no explanation, and the description still covers the interactive rendering caveat, the no-diagram fallback, and input resolution. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description largely restates the same accepted inputs. The one additive detail is the parenthetical '(the closest post or case study)', which clarifies topic resolution is nearest-match rather than exact, but that is a marginal gain over 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?

Names a specific verb ('walk through') and a precise resource ('a published techfabric.com post or case study'), then defines the output shape: diagram steps in flow order, each tied to its section with that section's opening text and a link. The 'interactive walkthrough of a published page' framing cleanly separates it from sibling write/lint tools and from plain page retrieval like get_page or preview_diagram.

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 the accepted input forms (URL, slug, or topic) and concrete trigger phrasings ('walk me through this post step by step', 'explain the diagram in this case study'), which tells the agent the user intents this tool serves. It does not name alternatives or state when another sibling should be used instead, so it stops short of full when/when-not routing.

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

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

Adds substantial context beyond the annotations: it explains why readOnlyHint=false (the topic is claimed to you for 24 hours), confirms idempotency in plain language ('asking again returns the same one'), states the auth requirement (Microsoft sign-in, scope blog.write), and notes 'No model is called.' The failure path (status none with a reason, then stop) is also 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?

Dense but efficient: authentication, claim behavior, payload, failure mode, and next step all appear in a compact block. The parenthetical and semicolon chaining make it somewhat run-on, but no sentence is filler.

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

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

An output schema covers the return values, and the description supplies everything else an agent needs: auth scope, claim/idempotency behavior, the handoff to submit_draft, and what to do when the response is empty.

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?

Zero parameters, so the baseline is 4; the description correctly introduces no parameter expectations and instead points at the returned brief_id that feeds submit_draft.

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 resource and payload: today's topic for a daily post, comprising topic, angle, target search, sources, internal links, and brief_id. It is clearly distinguishable from get_brief_pool (pool of candidates) and propose_brief, and the 24-hour claim semantics are stated up front.

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 routing: pass brief_id to submit_draft, and 'stop there' when status is none. It also instructs the agent to ask the engineer for first-hand detail rather than invent it. It doesn't explicitly contrast with get_brief_pool or propose_brief, which is the only 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?

Annotations already cover readOnly, idempotent, non-destructive, and closed-world, but the description goes well beyond them: it states the exact auth precondition (TechFabric engineer Microsoft sign-in, scope blog.write, site owner only) and that the automation runs as that user. It also declares determinism ('no model') and 'changes nothing'. What is left out is whether the 30-post window is fixed or truncated paging behavior — a minor gap given the annotations already signal a safe read.

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 with no filler, and the behavioral claims (deterministic, changes nothing) close it out cleanly. The auth constraint is front-loaded ahead of the actual purpose, which costs a little scanability — an agent skimming for 'what does this return' has to read past the sign-in clause first.

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 shape needn't be described, and the description still characterizes the payload contents and its window sizes. Combined with the disclosed auth requirement and determinism guarantee, an agent has everything needed to decide whether it can call this tool and what it will get.

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 no parameters (additionalProperties: false, empty properties), so per the baseline there is nothing for the description to disambiguate. The description correctly adds no invented parameter guidance and instead spends its words on scope and auth.

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 enumerates the resource precisely: briefs proposed but not taken, uncovered competitor-gap/backlog searches, the 30 most recent posts, and ideas in flight. The verb is implicit in the fragment 'A read:' rather than stated as 'returns/reads', but the content makes the tool's job unambiguous to an agent. It never names a sibling such as get_brief or list_posts, so differentiation is inferred from the enumerated contents rather than stated.

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?

'What the brief automation reads before it proposes' gives the agent a situational frame, implying this is the candidate-gathering step before propose_brief. However, there is no explicit 'use this when' or exclusion against get_brief, list_posts, or suggest_links_and_topics, so the routing must be inferred from the enumerated payload.

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, and closed-world, so the safety profile is covered; the description adds genuine context on top — that only published, indexable pages are reachable and that drafts require a Microsoft-authenticated engineer. It does not describe behavior for unpublished or unknown URLs, which would have completed the picture.

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 what is returned, followed by input forms and scope limits, in three tight sentences. The closing sentence on draft auth requirements is slightly tangential for a read tool but earns its place by preventing a wrong-tool selection.

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

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

With an output schema present, the description needn't explain return values, and annotations cover the safety profile, leaving scope, inputs, and draft routing — all addressed. The only real gap is error/not-found behavior for unpublished or nonexistent URLs.

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 parameter's schema description already lists URL, path, and slug. The description's "takes a URL, a path or a post's slug" mostly restates it, adding only the implicit note about which slug form is expected. Baseline 3 fits a case where the schema does the work.

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 — reads one published page of techfabric.com and returns it as clean Markdown — and enumerates the returned fields so an agent knows exactly what it gets. The scope word "published" distinguishes it from the draft-oriented siblings without needing to open 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?

Explicitly says which inputs are accepted (URL, path, slug), restricts to published/indexable pages, and routes draft needs to list_drafts with the auth prerequisite spelled out. The exclusion for drafts is clear, though other plausible alternatives (check_draft, preview_draft, get_brief) are not named.

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 declare read-only, idempotent, non-destructive and closed-world behavior. The description adds useful context by saying entries are exactly as the live page states them and that this is a complete catalogue, though it does not discuss auth or rate limits.

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

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

Two sentences, both front-loaded and useful: the first defines the catalogue contents and fields, the second points to get_page for full reads. There is no wasted text.

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 zero parameters, rich annotations and an output schema, the description supplies enough context: what the catalogue covers, what fields it includes, and where to go for full page content. No critical agent-facing information 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 there is no parameter semantics to clarify. The empty schema is consistent with a no-argument catalogue tool, and the description correctly does not invent 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 names the specific resource and scope: every service, solution, Databricks, AI, cloud, software, accelerator and product page on techfabric.com. It also specifies the returned fields (name, URL, kind, summary), so an agent can distinguish this catalogue tool from get_page.

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 routes full-detail reads to get_page, which is the key alternative. However, it does not compare itself with search or state when not to use this broad catalogue 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?

Surfaces an auth prerequisite the annotations can't express ('Requires a TechFabric engineer's Microsoft sign-in (scope blog.write)') and explains why readOnlyHint=false is set - form:true actively asks the engineer a question rather than just reading. It additionally warns that stored Markdown/base_hash can be stale because the engineer may have saved in the draft app, which is real behavioral context beyond the annotations.

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

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

Dense but almost every clause carries a constraint, a routing target, or a returned field, and the auth prerequisite plus the purpose are front-loaded. The nested parentheticals and one long sentence make it heavier to parse than necessary for what is fundamentally a status lookup.

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 enumerating next_action, base_hash, preview link, and live_url is partly redundant, but the description earns it by tying base_hash to update_draft and by explaining the form:true branch. The remaining gap is that 'A fact the blog writer waits on is in the status' is left vague about which field carries 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 description still adds value: it explains the behavioral consequence of form:true (asks the fact as a form vs. surfacing it in chat) and the role of `id` as a draft/idea identifier. Minor friction: the description calls it a draft id while the schema calls it 'The idea id', which leaves a small ambiguity about what identifier to supply.

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 ('Where one of your drafts stands ... by its id') and enumerates what comes back: next_action, saved Markdown, base_hash, failures, last check, preview link, live_url. It also names the sibling tools it is not (list_drafts, open_editor, preview_draft), so the agent can place it instantly.

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 routing in both directions: 'list_drafts lists them' for discovery, 'to edit in the browser, call open_editor', 'to show the engineer the draft itself ... call preview_draft, never fetch the preview link'. It also gives a usage rule inside the workflow: 'read them again before each edit'.

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 context beyond the annotations: Microsoft sign-in with blog.write scope, roughly a second, no credits, and no filing (consistent with readOnly/idempotent). It also discloses that lint results arrive as rewrite_plan and that judge_rubric comes back once checks pass, which the annotations alone don't say. Only slight gap is that failure behaviour beyond the plan is left implicit.

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?

Compact and mostly front-loaded, but it opens on the auth prerequisite rather than the purpose, and the check list is a dense parenthetical. The iterate/never-with-check_draft sentence earns its place; nothing is clearly wasteful.

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

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

With an output schema present, return values need not be explained, and the description covers auth, cost, side effects, the alternative tool and the iteration loop. What's missing is marginal: how failures are surfaced or how the plan is ordered.

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 id, kind, slug, images, rubric, sources, markdown and post_type in depth. The description only restates the id behaviour (saved text vs. markdown-as-edit) and adds no syntax or format detail beyond the schema, which is the baseline case.

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: the site's rule-based checks (slop, claims, known errors, voice, opening, title, description, FAQ, diagram, images, links, case-study rules) run on a post's Markdown including frontmatter. It also explicitly names the sibling it is not (check_draft), so an agent can distinguish it 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?

Gives an explicit routing rule — "Iterate with this, never with check_draft" — plus the loop: rewrite each passage in rewrite_plan as its fix says, lint again until ready, then review against judge_rubric. This is when-to-use, when-not-to-use and the alternative, all 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 readOnly/idempotent/non-destructive, but the description adds an auth requirement (TechFabric engineer's Microsoft sign-in, scope blog.write) that is not in any structured field. 'A read' and 'Posts nothing' reinforce no-side-effect behavior, and enumerating the check categories tells the agent what feedback to expect.

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

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

Front-loads the auth requirement and 'A read', then packs the check categories into a compact parenthetical list, and closes with the no-posting guarantee. It is dense but each clause earns its place; the single flowing sentence is slightly harder to scan than a short structured list would 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?

Output schema exists so return format need not be explained, and the description still covers auth, the scope of checks, iteration guidance, and side-effect guarantees. 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 schema already documents both parameters, but the description adds the conditional effect of the optional post parameter ('with post, whether it links the post') and reinforces text as the primary input. This is meaningful added semantics over the schema, though one could go further on length/format details.

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?

A specific verb (lint) applied to a specific resource (a LinkedIn post's text), and it enumerates exactly what is checked: site writing rules plus social rules (AI tells, slop, claims, announcement openers, engagement bait, hashtags), length, the 'see more' preview, and link presence when post is set. The scoping to a published LinkedIn post's text clearly separates it from draft-linting siblings like lint_draft or check_draft.

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?

'Rewrite each finding and lint again until ready' gives an iteration workflow, which is useful usage context. However, it never names the natural alternatives (lint_draft, check_draft, review_before_publishing) or states when-not to use this tool, leaving the routing to siblings implicit.

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 and non-destructive behavior; the description adds the Microsoft sign-in requirement and blog.write scope, plus ordering ('newest first') and that it 'Reads only'. It does not cover response format or rate limits, but with annotations and an output schema those are less critical.

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 one dense, run-on sequence with nested parentheticals, making it harder to scan than necessary. Much of the state and field enumeration duplicates the 100%-covered schema, though the auth note and sibling pointer are front-loaded and useful.

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

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

For an eight-parameter, permission-sensitive list tool, the description covers auth scope, role-gated parameters, filtering, cursor pagination, ordering and the follow-up get_status call. With an output schema and rich annotations already present, nothing an agent needs to invoke this correctly appears 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 eight parameters, including the editor-only and owner-only refusal semantics. The description's parameter text largely mirrors the schema, adding little beyond the baseline for full schema 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?

States a specific verb and resource ('Lists your drafts') and scopes it to drafts including blog posts, case studies and revisions. It also distinguishes itself from get_status by telling the agent to use get_status for one draft in detail, so it is separable from a sibling 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?

Gives clear operating context: filter by state/kind/date, page with cursor, editor-only 'all', site-owner-only 'stale', and 'Then get_status with an id for one draft in detail'. It does not explicitly rule out list_posts or other siblings, but the draft-scoped usage 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the description earns credit for adding what annotations can't: results are published-only, ordered newest first, and drafts are private. The auth/connection requirement is a genuinely useful behavioral disclosure beyond 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?

Two sentences, front-loaded with the resource and sort order before the filters. The second sentence is dense — two semicolon-separated clauses about draft privacy and the Microsoft connection — but each clause carries distinct routing information.

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

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

For a four-param, fully annotated read tool with an output schema, this covers purpose, default ordering, filter scope, exclusion of drafts, and the sibling + auth path for drafts. 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% and each parameter already documents itself (tag name or slug, author name or slug, YYYY-MM-DD since, limit default 20). The description only restates the filter set at a high level without adding semantics such as combining filters or the limit cap, so baseline 3 applies.

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

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

States a specific resource and scope: 'TechFabric's published blog posts, newest first,' plus the three optional filters. It also explicitly excludes drafts and names list_drafts as the tool that handles them, so an agent can separate it from that sibling without opening either schema.

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

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

Clearly sets the condition for this tool (published posts, optionally filtered) and routes drafts to list_drafts, including the prerequisite that a TechFabric engineer must connect with Microsoft to list/write drafts. It does not differentiate from other read siblings like search or get_page, but the listing role is unambiguous.

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 substantial behavior beyond annotations: required Microsoft sign-in with blog.write scope, single-use link, 15-minute expiry, presentational constraint never to fetch the link, access limited to the engineer's own drafts/posts with site-owner exception, and a note that the email editor link is unaffected. Annotations already mark it non-read-only and non-idempotent, and the description consistently reinforces that.

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 auth requirement and trigger are front-loaded, and most sentences carry distinct operational value. It is slightly dense and parenthetical in the parameter-routing sentence, and the final email-link sentence is useful but tangential.

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 an output schema, the description need not explain return values. It still covers auth, link lifetime, single-use behavior, presentation rules, access scope, and parameter routing, leaving no major operational gap for an agent invoking 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?

Schema description coverage is 100%, so the schema already documents `id` and `post`. The description adds only limited nuance: it clarifies that a published draft's id can be used with `post` and that the revision behavior matches revise_post, but it does not add new syntax, format, or exclusivity constraints beyond what the schema implies.

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 action and output: a browser-editor link that works once and expires in 15 minutes, for a draft or published post. It distinguishes the tool from revise_post by noting that `post` opens or finds the post's revision 'as revise_post does', making the boundary clear.

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: when the engineer asks to open or edit a draft or published post in the browser. It also gives a strong presentation rule ('Show it to them as a link and say so; never open or fetch it yourself'), but does not explicitly state when to use revise_post instead, only that the revision behavior is shared.

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 mark it read-only, idempotent, and non-destructive, and the description adds important behavioral context: auth scope, that it saves nothing, that invalid alt text returns a question rather than a snippet, and how decorative images are handled. These details go well beyond the structured annotations without contradicting them.

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 contains useful information and little outright fluff, but it is a dense run-on with awkward phrasing, especially the opening sentence about Markdown insertion. It is not front-loaded as cleanly as it could be, which makes the rules harder to parse quickly.

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 tool with an output schema and annotations, the description covers the key operational context: auth, image pre-upload, alt validation, decorative handling, placement, and no-save behavior. It could more explicitly route image uploading to request_image_upload, but the core completeness is strong.

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 seven parameters are already documented. The description reinforces alt-text and decorative behavior, but most parameter meaning is duplicated from the schema rather than adding new semantics beyond it. A 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?

It states a specific action: producing the Markdown for an already-uploaded image and the post with that image inserted after a named paragraph, while explicitly noting it does not save. It also distinguishes itself from update_draft for saving. The phrasing "A read:" is awkward, but the purpose is still clear enough for an agent to identify.

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 prerequisites (engineer Microsoft sign-in, image already uploaded), conditions for decorative images (only on the engineer's word), the alt-text requirement and refusal behavior, and the alternative action for saving with update_draft. It effectively covers when to use this tool and what not to do.

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: it discloses the auth requirement and scope (blog.write), a data-source caveat (US-only, totals lower than the all-countries view), a freshness/staleness bound (cached six hours), and an explicit no-side-effect/no-model guarantee. That is exactly the operational context annotations cannot carry.

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

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

Front-loads the auth prerequisite, then the core behavior, then the default case, then caveats — a sensible ordering with no filler sentences. The second sentence is very long and packs metrics, comparison window, and diagnosis into one clause chain, which costs readability slightly.

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

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

An output schema exists and the description still summarizes what comes back, so an agent knows both the shape and the caveats (US-only, 6h cache) before calling. For a single-optional-parameter read tool, 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 coverage is 100%, so the single 'post' parameter (URL or slug) is already fully documented, and the description's 'Without post: all your posts' merely restates the schema default. It adds one real nuance — ownership, i.e. 'your own published posts' with an editor exception for any post — but that is a marginal gain over a fully documented 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 ('A read: how one of your own published posts is doing in Google') and enumerates the exact metrics returned (clicks, impressions, CTR, average position, indexing status, recommendations). It also scopes the no-parameter case ('all your posts with their last 28 days'), so the tool is distinguishable from siblings like list_posts 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?

Explicitly routes the agent: this is a read, and the mutation path is named and gated ('revise_post changes a live post, only after the engineer agrees'). The 'Without post: all your posts' clause tells the agent how to widen scope. It stops short of naming alternatives for other adjacent questions (list_posts, get_status), but the when-to-use 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations: it discloses the auth requirement and scope, that nothing is persisted ('Files nothing'), that no model is called, and that rendering only happens in MCP Apps hosts. That host-dependent behavior is exactly the kind of trait annotations cannot express.

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 hard prerequisite, then the operation, then the per-block output, then the negative side effects and the sibling handoff, so no sentence is filler. It is dense and parenthetical-heavy, and the enumerated outcome clause runs long, which costs a point on readability rather than on 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?

Given an output schema, the return shape need not be spelled out, yet the description still characterizes what comes back per block. Combined with auth, side-effect and host-rendering disclosure, an agent has everything needed to decide whether and how to call 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 single parameter's description already states both accepted modes (whole post including frontmatter, or one mermaid source) and the 200,000-character cap. The description restates the dual-mode input but adds no format or syntax guidance beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource: it reads every ```mermaid block in a post (or a single mermaid source) and reports lines, caption, parse status with error location, and rule findings. It names the sibling it is not (lint_draft) and the drafting stage it belongs to, so an agent can separate it from lint_draft without opening either schema.

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

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

Explicit timing and alternative: 'use it while drafting, then lint_draft the whole post' tells the agent when to reach for this tool and what to do next instead of relying on it for whole-post checks. The precondition (engineer sign-in, blog.write scope) is stated up front rather than discovered at call 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?

Goes well beyond the readOnly/idempotent annotations: it names the required auth (Microsoft sign-in, scope blog.write), describes the inline MCP Apps rendering vs. other hosts, says the text begins with the preview link, and notes waiting behavior while the preview builds.

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

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

Front-loads the auth requirement and the read-only nature before the trigger phrases, and every sentence is functional. The quoted phrase list and the closing 'this is the preview' clause are somewhat repetitive, costing a point.

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 and annotations declare the safety profile, so the description's job is auth, rendering context, and invocation triggers — all of which are covered. 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% and the property descriptions for id, editing, instance and wait_seconds are already highly detailed. The description adds essentially no parameter-level information beyond a passing 'while the preview builds' hint, so the schema does all the work.

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 ('show one of your drafts') and pins down exactly what comes back: the draft as techfabric.com renders it, with its last checks and whether Publish may run. This distinguishes it cleanly from check_draft, lint_draft, open_editor and publish_draft.

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 a clear trigger list with literal engineer phrases ('show me the preview', 'open the preview', 'what does it look like') plus an explicit exclusion: never fetch the preview link yourself or rebuild the page as an artifact/HTML. It falls short of 5 only because it never names a sibling tool as the alternative for adjacent 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 only declare readOnly=false, idempotent=true, destructive=false. The description goes well beyond: it specifies the required auth (TechFabric engineer's Microsoft sign-in, scope blog.write, site owner's only, with the reason 'the brief automation runs as him'), states refusals store nothing, that 'the same topic again is the same brief' (matching idempotentHint with explanation), and that drafts and publishes nothing.

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 filler, with auth prerequisites front-loaded before behavior. The second sentence is dense — semicolon-separated refusal clauses and a trailing 'no model' fragment — but every clause carries information.

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

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

An output schema exists, so return values needn't be explained. Auth, refusal semantics, idempotency, and side-effect limits (nothing drafted or published) are all covered, which is everything an agent needs to invoke this mutation 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 83%, so the schema already documents all six parameters thoroughly, including 'why' and 'for_author'. The description enumerates the fields (topic, why, angle, sources, target_query, for_author) but adds little meaning beyond what the schema descriptions carry, and the key constraint that topic dedupes against existing work is behavioral rather than parameter-level. Baseline 3 fits.

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

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

'Adds one brief to the pool get_brief offers engineers' states a specific verb and resource and ties it to the consuming sibling, so an agent can distinguish it from get_brief, get_brief_pool, and start_post 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?

It enumerates the refusal conditions precisely (live post or idea in flight covers it, an open proposal already is it, today's 3 are used) and names the consuming sibling get_brief. What's missing is a positive 'call this when you have work worth turning into a brief' framing, but the downside cases are explicit.

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

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

Goes well beyond the annotations: discloses the Microsoft sign-in and blog.write scope, that it 'Saves nothing' (crucial since readOnlyHint=false could mislead), the hard limits (12 changes, 160 rewritten words each), and the human-in-the-loop decision step. Consistent with idempotentHint=true and destructiveHint=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?

Front-loads the auth prerequisite, then purpose, then mechanics and handoff — a sensible order with no filler. Slightly dense long sentence around 'ask: true, a form where the client shows one' costs a point on readability.

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?

A mutation-proposal tool with an output schema (redline_text), so return values needn't be explained. Auth, limits, non-persistence, the show-then-apply loop, and the form fallback are all present; 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 coverage is 75% and already documents id, base_hash, ask, and the nested change fields, so the baseline is 3-4. The description adds value the schema lacks: the 160-word cap per replacement, the exactness requirement for find, and the meaning of a blank replace ("" removes the passage) is emphasized at tool level.

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 (propose) and resource (changes to a filed draft as a redline the engineer decides on), and immediately positions it against siblings update_draft and apply_edits. An agent can distinguish propose_edits from apply_edits (accept/commit) and update_draft (direct writes) from the text alone.

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

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

Explicit routing: 'Use it for every fix to a filed draft, instead of update_draft', plus the follow-up path ('send what they accept to apply_edits'). It also names the escape hatch (ask: true when no draft app is showing), so when and when-not are both covered.

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, the description discloses the required Microsoft sign-in and blog.write scope, the fact that the first call publishes nothing, the confirmation handshake, and the restriction that override cannot bypass hard checks. These are significant behavioral details for a destructive, non-idempotent operation.

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 core action and safety prerequisite, but it becomes a dense run-on explanation of confirmation paths, override semantics, and token behavior. The information is useful, yet the structure is harder to parse than necessary.

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 covers the full workflow an agent needs: auth requirements, check prerequisites, engineer confirmation, two-step publishing behavior, override limits, and unattended-run prohibition. With an output schema present, return-value details need not be explained.

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 parameter descriptions already carry most of the meaning. The tool description reinforces override and confirm_via behavior in context, but it largely repeats what the schema says rather than adding new syntax or constraints.

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: publish one of your drafts to techfabric.com. It also ties the action to check_draft passing and engineer confirmation, which distinguishes it from sibling review, submit, and edit 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 gives explicit preconditions: the engineer must confirm, check_draft must have passed on exactly the saved text, and the tool must never run scheduled or unattended. It also explains the two-step confirmation workflow and when to use the token confirmation path.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description still adds real behavioral context: the quiz is answered in one of three modes (form, MCP Apps view, or plain text with the key withheld until the reader has answered), answers are scored on submit, and a stored resume code lets a reader pick up where they left off. It also discloses a non-obvious trait — the questions and answers are sourced from the post itself rather than generated — which an agent could not infer from 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?

It is front-loaded and every clause arguably carries information, but the middle sentences are run-ons that stack parentheticals ('Keep my progress, in a host without Fabric's view state'), which makes the mode-selection rules hard to parse on a single read. The content earns its place; the packaging does 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, return values need not be explained, yet the description still tells the agent that each question carries its answer, explanation and link. The main residual ambiguity is whether text mode requires one call (questions) followed by a second call with answers, or whether the unanswered-then-scored flow is returned from a single call — the description implies but does not state this.

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 3 would be the baseline; the prose goes beyond the per-parameter descriptions by explaining how the parameters combine — resume alone suffices ('the code names its post, so nothing else is needed'), answers are sent in question order as letters, and form is only for form-capable clients. That interaction logic is not spelled out 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 first sentence states a specific verb and resource: 'a multiple-choice quiz from a published post's own FAQs', and then defines the question/answer provenance exactly ('each question is one of its FAQs, the right option is the post's answer, and the others are answers the site gives to other questions; no model writes them'). No sibling tool does anything similar, so it is trivially distinguishable from the rest of the toolset.

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 invocation triggers ('quiz me on this post', 'test what I learned', 'check my understanding') and conditions the form parameter on 'a client that shows forms and no MCP Apps view'. It does not name any sibling alternative or exclusion (e.g., when to use explore_post or ask_author instead), so it stops just short of the top mark.

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 readOnlyHint/idempotentHint it discloses the auth requirement and scope, and explicitly negates side effects: 'No model is called and nothing is posted, voted or commented.' It also previews the output contents (rules, frame, disclosure line, checklist, posting steps), which is exactly the behavioral context an agent needs before calling.

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?

Length is reasonable for a 5-parameter tool, and the auth prerequisite is front-loaded. But the prose is telegraphic and run-on — fragments like 'A read:' and 'Send draft to check it:' pack the lint-and-rewrite loop into a sentence that reads as a separate capability, costing clarity.

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

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

With an output schema present, return values needn't be explained, and the description covers auth, inputs, style constraints and the rewrite loop. What it leaves ambiguous is whether one call produces both the drafting kit and lint, and how it differs from check_draft/lint_draft.

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 every parameter is documented inline, so the baseline is 3. The description adds only ambient meaning — that output is tailored to the target subreddit's rules and that the post/notes inputs are the raw material — without new syntax or format guidance 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?

It names a concrete resource and scope: a read that returns everything needed to draft a Reddit post or thread answer from a techfabric.com post or notes. The second half adds a second apparent capability (send a draft and get lint back), which slightly muddies what the tool actually returns, and it never names the sibling it supersedes for non-Reddit channels (social_post_kit).

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?

'Requires a TechFabric engineer's Microsoft sign-in (scope blog.write)' plus 'from a published techfabric.com post or your own notes' gives a clear trigger condition and precondition. It also states the iteration loop ('send it again after each rewrite until lint.ready is true'). No exclusion or explicit alternative is given, so it stops short of a 5.

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

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

Goes well beyond the annotations: discloses the auth scope required, the 15-minute single-use nature of the URL, size/format/count limits, metadata stripping, and a security constraint on token placement. The 'token only in the header, never in the URL' instruction is exactly the behavioral context an agent needs before calling.

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

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

Front-loads the auth prerequisite and the core action, then the returns, then the next step. Sentences are long and heavily parenthesized, which costs some readability, but nearly every clause carries operational information.

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

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

An output schema exists, yet the description still summarizes the return (upload URL, Authorization header, curl command), which is more than required. Combined with auth, limits, metadata handling, and the place_image handoff, nothing an agent needs 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 already 100%, so baseline is 3, but the description adds real meaning: alt must be the engineer's own words and must never be generated by the agent, and only one file type matching the declared content_type is accepted. The 'file of the type given' constraint reinforces the enum relationship between filename and content_type.

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 ('adds an image to one of your own drafts') and scopes it away from the browser editor, which is the natural sibling/alternative. The link to place_image makes the workflow position 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?

Clearly sets the precondition (TechFabric engineer sign-in, blog.write scope, own drafts only) and names the follow-up tool, place_image. It does not explicitly name open_editor as the alternative for browser-based uploads, so the exclusion 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 mark it read-only, idempotent and non-destructive, and the description adds material behavior on top: a required Microsoft sign-in with blog.write scope, a single-use confirmation bound to the exact saved text and its checks, and defined failure output. That is exactly the context an agent needs about auth and token lifetime, neither of which the annotations express.

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

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

The content is dense and mostly earns its place, but the auth requirement is front-loaded ahead of the actual purpose, and the sentence 'A read: whether one of your drafts may be published now...' is awkwardly constructed. Leading with the check and following with auth and the follow-up call would be easier to parse.

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 doesn't need to enumerate return values, and it covers auth, the success path, the failure path and the handoff to publish_draft. One gap: it never says whether check_draft/lint_draft should be run before this, despite referring to 'its checks' as though that were established.

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 goes further by explaining that the confirmation is one-time and tied to this exact text, and that the override must be passed identically to publish_draft. That cross-tool coupling is not derivable from the schema alone, though it still doesn't explain what happens if the same confirmation is reused.

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 specifies a read-only check on one of the caller's own drafts and states what it returns: a publishability verdict plus a ready-made question to ask the engineer. It names publish_draft as the downstream tool, which differentiates it from siblings, though the framing 'A read:' is indirect and the core verb (check/review publishability) is buried after the auth sentence.

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 ordered workflow: call this first, and only after the engineer says yes call publish_draft with the id, the confirmation, and the same override. It also covers the negative branch ('if it can't be published yet, it says why and what to do'), so there is no ambiguity about sequencing or alternates.

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 annotations already declaring idempotentHint and destructiveHint, the description still adds substantial context: the auth scope, the author/editor-only restriction, that the revision's draft is seeded from the live text with its own preview, that publishing replaces the post at the same URL and byline while keeping the date, and that repeated calls return the already-open revision. That last point corroborates idempotency with concrete behavior rather than contradicting it.

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

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

Front-loads the prerequisite and then walks the loop in order, with almost no wasted words. It is telegraphic in places ('then the same loop') and leans on prior knowledge of the sibling workflow, which slightly reduces standalone clarity.

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; the description covers prerequisites, permissions, side effects (same URL/byline, preserved date), and the downstream tool chain. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% for the single 'post' parameter, so the baseline is 3. The description adds real semantics beyond the schema: the target must be a *live* post (not a draft), and it restates the URL-or-slug freedom of the 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 and resource: 'Open a revision of a post that is live on techfabric.com, by its URL or slug'. The 'live post' qualifier distinguishes it from start_post (new draft) and update_draft (edit a draft), so an agent can route correctly 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 clear preconditions (Microsoft sign-in with blog.write scope, caller must be the post's author or the blog editor) and spells out the follow-on loop: get_status, lint_draft, update_draft, check_draft, publish_draft. It does not explicitly state when *not* to use it (e.g. drafts vs. live posts named as a sibling alternative), so it stops short of a 5.

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

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

Goes beyond readOnlyHint/idempotentHint by describing result ordering ('best first') and the exact payload fields (title, URL, summary, date, author, type), plus the drafts-privacy/auth boundary. The only shortfall is that ordering semantics aren't quantified (relevance vs. date) and there is no mention of empty-result 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?

Front-loaded with the core search scope, then the return shape, then a routing sentence. The final sentence about drafts and Microsoft connection is slightly long and mixes in sibling-tool and auth context, but it earns its place by preventing a wrong tool choice.

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 three-parameter, fully documented read tool with an output schema, the description covers scope, return contents, ordering, and the draft boundary. Missing only minor operational details like empty-result handling and what the relevance ranking is based on.

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 query, type enum, and limit are already fully documented, including the default of 10 and the max of 25. The description adds no parameter-level detail beyond that, so 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?

States a specific verb (Search) against a specific resource (TechFabric's published site) and enumerates the content types covered: blog posts, service and solution pages, case studies, city pages, events. An agent can distinguish it from list_posts or get_page 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?

Explicitly routes the agent: use get_page to read a result in full, use list_drafts for private drafts, and notes an engineer must connect with Microsoft to list or write them. It also states drafts are excluded from this tool's scope, which is an explicit when-not.

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 bar is lower; the description still adds real value by naming the auth requirement (Microsoft sign-in, blog.write scope) and by stating 'No model is called and nothing is posted.' It also enumerates what the response contains, which is useful orientation even though an output schema exists. Missing only things like rate limits or behavior for an unpublished/unknown slug.

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?

Every sentence carries information and the prerequisite (sign-in scope) is front-loaded, followed by what is returned and the workflow. The middle enumeration of kit contents is a comma-spliced list of fragments that reads a little breathlessly, but nothing is redundant.

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

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

For a read-only, single-parameter tool with annotations and an output schema, the description covers the essentials: access prerequisite, contents, absence of side effects, and next steps. It would be fully complete with a note on what happens when the supplied post is not published.

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?

A single parameter with 100% schema description coverage, so the schema already explains the URL/slug format. The description adds one genuinely useful clarification — 'any post on the site', not just the engineer's own — but provides no error semantics for unpublished posts or invalid slugs. That is the expected baseline-3 level when 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?

States a concrete verb and resource: reads a drafting kit (key points, first-hand sentences, campaign link, voice notes, social rules, LinkedIn lengths) for a published techfabric.com post. The LinkedIn scope implicitly separates it from reddit_post_kit, and it explicitly hands off to lint_social. The wording 'A read: what your agent needs to draft...' is a bit indirect as an opening statement of purpose, keeping it just 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 an explicit workflow: draft the post from this kit, validate with lint_social, then show the engineer the text so they post it themselves. That is clear when-to-use guidance and names the correct downstream sibling. It lacks an explicit exclusion (e.g., 'for Reddit posts use reddit_post_kit'), so it stops at 4.

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

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

Beyond the readOnly/destructive annotations, it discloses the auth prerequisite (Microsoft sign-in, scope blog.write, TechFabric engineer only), the side-effect profile ("A read: nothing is filed or claimed"), and the two-call interview loop. It does not cover what happens if the sign-in is missing or expired, nor any retry/failure behavior, which keeps it short of a 5 for a tool with this much interaction surface.

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 trigger statement is front-loaded, but the body is a dense run-on chain of clauses ("about seven questions tailored to the topic and to today's brief. First look through the repository, and the site with search and get_page, then send suggested...") that mixes workflow, permissions, and parameter notes in one breath. Little is outright wasted, yet the ordering and sentence length make it harder to parse than it needs to 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?

For a zero-required-parameter, nested-object tool with an output schema present, the description covers the parts structured fields cannot: auth, the discovery steps before suggesting answers, the confirm-or-correct intent of 'suggested', and the required handoff sequence to submit_draft/outline/check_outline. Nothing an agent needs to call this correctly and route the result 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 seven parameters, and the description largely restates them: form behavior, topic vs brief, answers, suggested. Where it adds real meaning is the sequencing rule that suggested must come from the repository and notes and is "never sent as their words," and the distinction between suggested and answers, but that is incremental over 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?

"Start here when asked to write, draft or start a blog post or case study for techfabric.com" names the verb, the resource and the exact trigger, and the description immediately distinguishes itself from siblings by pointing forward to submit_draft, outline and check_outline and by warning it is "never a local file." An agent can tell this is the entry-point interview tool, not the drafting or editing tools, 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 explicit when-to-use (before writing anything, even inside the techfabric-web repo), when-not (never a local file), and named follow-on alternatives (search and get_page first, then submit_draft, outline, check_outline before any prose). The two-phase interaction is spelled out: ask in chat and call again with answers, or pass form: true only when the client supports forms and the engineer wants one.

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 substantial context beyond the annotations: the required Microsoft sign-in with scope blog.write, the side effect that the site builds a preview and emails it to the engineer, the return values (id and text_hash), and the explicit guarantee that it never publishes. Idempotency is already declared by annotations, and the description doesn't restate it, which is correct. The remaining gap is minor: it doesn't say what happens on lint failures or validation rejection.

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 critical constraints are front-loaded: auth, then what gets filed, then what to send, then the next step, then 'Never publishes'. It is dense but nearly every clause carries a rule; the staccato fragments ('Lint it clean first.') and the long middle sentence on markdown slightly hurt readability.

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

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

For an 11-parameter mutation tool with an output schema and annotations, the description covers auth, side effects, return values, sequencing and the no-publish guarantee. Images and client_confirmed are not mentioned, but the schema documents both in detail, so the omission is not blocking.

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 already 91%, so the baseline is 3; the description earns above that by tying parameters to workflow conditions ('brief_id when it comes from get_brief', 'from_idea when it continues an idea they emailed') and by stating the frontmatter minimum ('title and description at least') and that sources must be the engineer's own quoted words. It leaves images, post_type and client_confirmed to the schema, which is reasonable at this 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?

States a specific verb and resource ('File a post ... under the engineer's byline, exactly as written') and immediately scopes the variant ('with kind "case-study", a case study'). It also distinguishes itself from publish_draft ('Never publishes') and points forward to check_draft, so an agent can place it in the workflow 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?

Gives explicit preconditions and sequencing: 'Lint it clean first', use brief_id 'when it comes from get_brief', from_idea 'when it continues an idea they emailed', and 'next, check_draft with the id'. It also rules out the publishing alternative outright, leaving little to infer about when to call this versus its 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?

Annotations already cover readOnly/idempotent/non-destructive, and the description adds genuinely new context: it requires a TechFabric engineer's Microsoft sign-in with the blog.write scope, it is deterministic with no model involved, and it excludes links the post already contains. The auth requirement and determinism claim are not in the structured data and matter for calling it.

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?

Everything is crammed into one rambling, unpunctuated-in-places paragraph that opens with an auth prerequisite before stating the purpose. Every clause carries information, but the core function is buried mid-sentence and the grammar is awkward, hurting scanability.

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 shape need not be explained. For a no-required-parameter, side-effect-free lookup, the description covers auth, input modes, determinism, the no-duplicate-links guarantee and the topics-only mode — an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the schema already explains id, post and markdown. The description still adds meaning the schema does not: that supplying nothing yields topics only, and that markdown with an id overrides the draft's saved text. That empty-args semantics is real added value above 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 specific verb and resource: it returns the internal pages a draft/post should link (with why and where) plus open searches that match the user's work. The two-part output is clear and no sibling tool in the list does the same thing, but the phrasing is convoluted ("the pages of ours a draft or post should link") and never contrasts itself with neighbors like check_draft or get_brief.

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 concrete invocation modes — send markdown, an id for a draft, a post URL/slug, or nothing at all for topics only — which is useful routing. However it never says when to use this instead of the adjacent tools (check_draft, check_outline, review_before_publishing) or any exclusion, so the when-to-use decision remains inferred.

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

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

Goes well beyond the annotations: states the required sign-in and scope (blog.write), that the call is refused if the draft changed since base_hash or is open in the browser editor, that the preview rebuilds asynchronously, and that it never publishes. This gives the agent the failure modes and side effects that destructiveHint=true alone does not explain.

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 auth requirement and the core payload (whole Markdown + base_hash), then failure modes, then concurrency. It is dense with parenthetical cross-references and the last two sentences overlap slightly, but every sentence carries operational information.

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

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

For a 10-parameter mutation with an output schema, the description covers auth, required payload, staleness checks, concurrency with the human editor, ordering with lint_draft/check_draft, and the no-publish guarantee. Return values are covered by the output schema, so nothing essential 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 baseline is 3, but the description adds cross-tool provenance for base_hash (draft.base_hash from get_status, or the text_hash returned by the previous update_draft) that the schema only partly restates. The remaining parameters (first_hand, client_confirmed, app_instance) are documented in the schema rather than the description, which is acceptable here.

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?

Specific verb and resource: 'Save a new version of your draft (state drafted): the whole Markdown, and base_hash'. 'The whole Markdown' implicitly contrasts with patch-style siblings like apply_edits, and 'Never publishes' rules out publish_draft/submit_draft. It never names the closest alternative (apply_edits/revise_post) explicitly, so the differentiation is inferred rather than stated.

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 sequencing and alternatives: 'It runs no checks: lint_draft the edit first, then check_draft with the id', plus 'start each edit from a fresh get_status' after any in-app save. It also names the exact source of base_hash (get_status or the last update_draft's text_hash), so the agent knows what to call before and after.

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

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

Annotations already declare this a safe, idempotent read, yet the description still adds real behavior: the tool validates that the document will render and returns an error listing what to fix, it does not verify factual claims, it echoes the entire card as text with a one-line handoff, and it labels the card as composed by the agent. Source restriction to pages the site publishes and the MCP Apps host vs. plain-text behavior are also 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?

The purpose is front-loaded, but the body is a single long run-on paragraph dense with semicolons, parentheticals, trigger lists and alternatives. Nearly all content earns its place, yet the lack of structure makes the when-to-use and failure-mode information harder to extract than it needs to 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?

For a complex tool requiring a structured A2UI document, the description covers the input contract, validation/failure behavior, source provenance, rendering fallback, attribution labeling and sibling alternatives; since an output schema exists, return-value detail is correctly left out. Nothing an agent needs to call it correctly appears 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 parameters are already documented, and the catalog ID / catalogId list is spelled out in the schema itself. The description adds only light extra meaning (sources must come from search/get_page, only this site's pages are cited). Baseline 3 is appropriate since 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?

States a concrete verb+artifact: draw the answer as a card by writing an A2UI v0.9.1 document, and enumerates the card shapes (comparison with verdict, plan as steps, calculator, quiz, table, diagram). It also distinguishes itself from siblings by routing posts, case-study comparisons and readiness checks to explore_post, compare_case_studies and assess_databricks_readiness.

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

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

Gives an explicit trigger rule ('Call it whenever the answer has a shape'), literal user phrasings to match ('compare', 'X vs Y', 'pros and cons', 'roadmap', 'show me', 'draw', 'chart'), a negative rule ('rather than answering with a long Markdown table or list'), named alternatives for the excluded cases, and the prerequisite to fetch facts with search/get_page first.

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