TechFabric

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

It adds substantial behavior beyond the annotations: Microsoft sign-in with blog.write scope, an anonymous sign-in challenge, no filing, a 5-10 minute runtime, tasks-extension polling versus wait_seconds progress return, and idempotent rereads. These operational details are not in the structured annotations and are exactly what an agent needs.

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 dense but each sentence carries operational information, including auth, duration, polling, and return behavior. It is not perfectly front-loaded because it opens with the auth prerequisite rather than the tool's purpose, and the polling sentence is slightly convoluted.

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 check with an output schema, annotations, and three parameters, the description covers auth, runtime, polling/wait behavior, idempotency, and return shape. With the output schema handling findings details, nothing critical for correct invocation 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 67%, and the description references Markdown/frontmatter and images but adds little parameter-specific meaning beyond the schema. It does not explain wait_seconds default/max or the name-only image behavior beyond what the schema already documents.

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: run techfabric.com's readiness checks on a post's Markdown with frontmatter. The 'Files nothing' contrast and the return description distinguish it from submit/update siblings, so an agent can identify it as a pre-submission check.

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

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

It gives clear context for use as a readiness check on a draft's Markdown and notes that it files nothing, implying use before submission. However, it never names submit_draft or update_draft as alternatives or states explicit when-not conditions, so sibling routing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: the return being clean Markdown and the hard restriction to published, indexable pages. It omits rate limits or caching behavior, which is a minor gap given the annotation coverage.

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

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

Two tight sentences with zero filler. The returned-fields payload is front-loaded and the input/scope constraint follows immediately; every clause carries information.

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

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

With an output schema present and annotations covering safety, the description needn't explain return values, yet it does so comprehensively without harm. The only real gap is the absence of explicit sibling routing for draft content, but the tool is otherwise fully specified for invocation.

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

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

Schema description coverage is 100% and the single parameter's own description already lists URL, path, and slug forms, so the schema carries the meaning. The description restates the same three input forms without adding syntax examples or constraints beyond the 500-char max in the schema. 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 and resource: reads one published page from www.techfabric.com and enumerates exactly what it returns (Markdown, title, metaTitle, description, dates, author, tags, FAQs, canonical URL). 'One published page' inherently contrasts with list posts or services, but no sibling is named explicitly, so it stops short of a 5.

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

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

Gives the accepted input forms (URL, path, or slug) and a clear scoping constraint: 'Only published, indexable pages.' That constraint implies drafts must go through check_draft, but the alternative is not named outright, so it is strong context without explicit 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed world), so the bar is lower. The description still adds two useful traits beyond them: the result set is exhaustive ('Every ... page'), and field values are reported verbatim ('exactly as the live page states them'). It says nothing about result volume or pagination behavior for a whole-site catalog.

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, zero waste, with the scope and return fields front-loaded and the sibling routing deferred to the end. The category enumeration is long but informative about coverage rather than filler.

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

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

With an output schema present, return values need no explanation, and annotations cover safety and world assumptions. The only real omission is any indication of catalog size or pagination, which matters for a whole-site listing tool.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to carry; baseline 4 applies. Schema description coverage is 100% and additionalProperties is false, leaving nothing ambiguous.

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/resource ('Every service, solution, ... page on techfabric.com') and enumerates exactly what each item carries (name, URL, kind, summary). It also names the sibling get_page as the way to read a single item in full, so an agent can distinguish it from get_page without opening either schema.

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

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

Gives a clear use context (enumerate the full catalog of offering pages) and explicitly routes deep reads to get_page. It stops short of distinguishing itself from the other retrieval siblings such as search or list_posts, so the when-not guidance is partial.

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?

This is the description's strongest dimension: it discloses the auth requirement and scope (blog.write), the anonymous-sign-in challenge behavior, the ephemeral nature of the editor link (yours for a day), and that the tool may block to request a fact from the caller. That also explains why readOnlyHint is false for a 'status' tool — it mints a link and can prompt — so the description and annotations are consistent rather than contradictory.

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

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

Three dense sentences, each carrying distinct load — auth, returned payload, and the interactive ask. Nothing is padded, though the long compound sentence listing return fields is harder to scan than a short 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?

Auth, scope, ownership restriction, failure/check-run reporting, base_sha hand-off to update_draft, link expiry, and the interactive-ask behavior are all covered, and an output schema exists to carry exact return shape. An agent has everything needed to call this correctly and interpret the result.

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 id parameter is documented as 'The idea id'. The description adds only the ownership constraint ('one of your own drafts'), which is mildly useful but mostly reiterates what the schema already conveys. Baseline 3 applies.

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

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

The description names the resource concretely ('One of your own drafts') and enumerates exactly what is returned: state, failing checks, last check run, Markdown, base_sha, and preview/editor links. It is not a bare restatement of 'get_status'. However it never explicitly distinguishes itself from the similarly named sibling check_draft, so an agent must infer that boundary.

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?

Scope is implied ('one of your own drafts') and there is one real usage cue — base_sha exists 'for update_draft' and the tool 'asks you for it first' when a fact is needed. But there is no explicit when-not guidance and no differentiation from check_draft or get_page, leaving the agent to guess which status-ish tool to call.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds one genuinely behavioral fact not in annotations: results are returned newest first. It says nothing about pagination, result caps, or behavior when no filters match, so it stays at baseline-plus.

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

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

A single sentence that front-loads the resource and ordering, then the filters. Every clause maps to real behavior and there is no filler.

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

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

With a full output schema, complete annotation set, and 100% schema coverage, the description only needs to add the ordering and filter semantics, which it does. Minor gap: no mention of default paging behavior or result limits, though the limit default is in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including patterns and the default limit of 20. The description restates tag/author/since but omits the limit parameter and adds no format or interaction detail 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?

States a specific resource (TechFabric blog posts) and scope: sorted newest-first, with optional filters by tag, author, or date. An agent can tell it is a listing/query tool. It does not explicitly contrast itself with siblings like get_page or search, 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?

The word 'optionally' signals that filters are available but does not say when to reach for this tool versus search or the draft/page tools. Usage is implied by the filter list, with no exclusions or alternatives 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?

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value by disclosing the result shape (title, URL, summary, date, author, type) and ranking behavior ('best first'), which the annotations cannot convey.

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

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

Two sentences, front-loaded with the scope and wrapped up with the natural next step. No filler or restated title content; 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-value detail is optional, yet the description still previews the fields. Scope, ranking and the follow-up tool are all covered. The only omission is any hint about result volume/pagination behavior, which is minor given the limit parameter and 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 description coverage is 100% — every parameter (query, type, limit) is documented in the schema itself with enums and bounds. The description adds nothing about parameter syntax or defaults; the only extra semantic is ranking order, which is not a parameter. Baseline 3 applies.

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

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

States a specific verb (Search) plus the exact resource and content scope: 'TechFabric's published site: blog posts, service and solution pages, case studies, city pages and events.' An agent immediately knows the corpus being searched. It partially differentiates from siblings by pointing to get_page for full reads, but never contrasts itself with list_posts or get_services.

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?

'Read a result in full with get_page' gives a clear follow-up path, which is useful. However, it never says when to prefer search over the sibling listers (list_posts, get_services) or what happens when the query is too broad. Usage is implied by the query parameter rather than explicitly guided.

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 past the annotations (readOnly=false, idempotent=true, destructive=false, openWorld=false) by disclosing the auth requirement and exact scope (blog.write), the anonymous-call failure mode, the no-rewrite/no-fact-check contract placing authoring burden on the caller, the downstream side effects (diagram rendering, media storage, preview email with editor/approve links), and the tasks-extension completion signal. No statement conflicts with the annotations.

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

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

Front-loads the highest-risk constraint (sign-in and scope) and keeps to one paragraph with no filler, but several clauses are densely nested in parentheses, which slows scanning for the core submit action.

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

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

With no output schema, the description still closes the loop by naming the return value (the idea id) and the asynchronous completion path for tasks-extension clients. Combined with the auth, side-effect and no-publication disclosures, an agent has everything needed to call this 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 67%, and the description compensates by specifying that markdown must contain frontmatter with at least title and description, and that the draft is stored exactly as sent. It does not describe how images entries map into the post beyond what the schema's alt/data/name descriptions already say, so it adds real but partial meaning.

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

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

States a specific verb and resource — files a post into techfabric.com's blog pipeline under the signed-in engineer's byline — and the mass-noun scope (draft, not published). It is clearly distinguishable from check_draft (validates) and update_draft (edits existing), so an agent can route 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?

Explicitly routes the agent: 'Run check_draft first; what the draft still lacks comes back as findings,' and constrains behaviour with 'Never publishes.' It does not say when to prefer update_draft over a resubmission, so the sibling coverage is strong but not complete.

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 discloses the auth requirement (Microsoft sign-in, scope blog.write) and that anonymous calls receive a sign-in challenge, the state precondition, the base_sha freshness requirement, and post-execution behavior ('commits it and rebuilds the preview'). None of this is in the structured fields, and nothing contradicts the annotation profile.

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 and mostly front-loaded, but the lead sentence is the auth precondition rather than the tool's action, and phrasing like 'only while it waits on you (state drafted)' takes work to parse. Every sentence still carries information; the cost is readability, not redundancy.

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

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

With no output schema, the description compensates by describing consequences (commit, preview rebuild) and explicitly ruling out publication. It does not state what is returned (e.g., a new sha) or what happens on a stale base_sha, which a save tool arguably should.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by tying base_sha to get_status and framing it as the version the edit started from, which conveys the optimistic-concurrency semantics the schema description only hints at. The id/markdown semantics are left largely to the schema.

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

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

States a specific verb+resource ('Save a new version of one of your own drafts') and anchors it to a familiar analogue ('as the browser editor's Save does'). It also explicitly separates itself from submit_draft ('Never publishes') and check_draft ('it runs no checks'), so an agent can distinguish it from siblings without opening a schema.

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

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

Gives explicit when-conditions: only in state 'drafted', only on top of the version you edited, and never while the draft is open in the browser editor. It also names the alternative tool for validation ('check_draft does') and explains that Run checks, not this tool, is what Publish needs.

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