btlabs Core

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

With no annotations, the description carries the full burden and does substantial work: it explains that a plain find returns only the published main-table state, that drafts are hidden unless draft:true, that public read is exposed via /api/agents, and it flags that MCP deletes are PERMANENT hard-deletes the admin Trash will not catch. The delete/capability chatter is largely irrelevant to a find tool and risks misleading an agent about what this call can do.

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 valuable scoping facts (required fields, draft behavior) are reasonably front-loaded, but the text degenerates into a fragment chain that mixes in inapplicable material — the delete permanence warning and the 'MCP capabilities' list belong to other operations, not this query tool. Several sentences could be cut without losing information an agent needs to call findFaqs.

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, annotation-free query tool with no output schema, the description supplies the context that matters most: draft/publish semantics, locale handling, relationship population via categories, and the writing-guidelines prerequisite. Return shape and pagination defaults are delegated to a fully documented schema, so little 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 100%, so the baseline is 3, but the description earns a bump by explaining semantics the schema does not: `draft` switches between the versions table and the published main-table state, and `_status` values control visibility. It also ties `locale` to the getWritingGuidelines call. `where`, `sort`, `select`, and pagination are left entirely to the schema, which is acceptable given full coverage.

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

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

The opening "FAQ entries." is a bare noun fragment rather than a verb+resource statement, and the explicit verb only appears buried in "MCP capabilities: find, create, update, delete", which lists operations this find tool likely does not perform. The field inventory (question, answer, categories) and the "a find WITHOUT draft:true..." clause do let an agent infer it queries the faqs collection, and the find* sibling family makes the resource obvious.

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 operational rules: use `_status:"published"` to go live, use `draft:true` to reach the versions table, and it names two alternatives with the condition that selects them — `schedulePost` for scheduling and `getWritingGuidelines` before writing public text. What is missing is any statement of when to prefer this over the sibling finders (findPages, findPosts, etc.).

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?

No annotations exist, so the description carries the full burden, and it does disclose real behavior: drafts are supported and non-draft finds hit the published main-table state, the collection is public-read via /api/agents, and shortDefinition is auto-consumed by tooltips and AI answers. It also warns that delete is a permanent hard-delete bypassing the admin Trash, which is valuable context even if it belongs to a sibling mutation tool rather than this find tool.

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 with a useful field-and-behavior dump but then appends a long schema recap ("Fields: title (localized), slug (localized), synonyms (localized), ... searchText (textarea, localized, ≤60000 chars, redacted), meta (group: ...)") that largely restates collection metadata. Capability, delete, and writing-guideline sentences target create/update/delete and add noise for an agent deciding how to call this read tool.

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 10 optional params at 100% schema coverage and no output schema, the description supplies the domain model, draft behavior, locale handling, and field inventory needed to form useful where/select clauses. It omits any hint about response shape or pagination totals, but pagination is already covered by the schema's page/limit descriptions.

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 earns an extra point by explaining draft semantics in a way the schema's vague wording ("versions table/collection") does not. It also enumerates the fields available for where/select/sort (title, slug, synonyms, tags, related, robots), giving the agent concrete field names the generic schema cannot 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?

The description opens with "Public glossary of terms," which identifies the resource but never states a clean verb+scope sentence like "retrieve glossary entries." The verb only surfaces obliquely in "a find WITHOUT draft:true returns the published main-table state" and in the boilerplate "MCP capabilities: find, create, update, delete," which lists four operations for a tool whose schema only supports querying. Sibling differentiation is mostly carried by the tool name (findGlossary vs findFaqs), not the text.

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?

There is a concrete conditional: "a find WITHOUT draft:true returns the published main-table state only," which tells the agent when to pass draft. It also routes to a sibling, "Before writing public text here, call getWritingGuidelines with this collection and the locale," but that guidance only applies to write operations, not to this read tool. No when-not-to-use or alternative-for-filtering guidance is given.

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 no annotations, the description carries the full burden and does substantial work: it discloses that MCP deletes are hard-deletes that bypass the admin Trash, that binaries cannot be uploaded here and must come via addMediaFromUrl (admin-only), that drafts are unsupported, that public read is available via /api/agents, and that aiAutofillStatus is redacted. The only weakness is that these write/delete behaviors are attached to a tool whose schema is read-only, which could mislead an agent about what this call can actually do.

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 useful but poorly structured: the permanent-delete warning is repeated twice, parenthetical asides are stacked mid-sentence, and the operation verb is buried after the resource definition. For a find tool, a large share of the text is devoted to delete and upload caveats that do not apply to this call.

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 10 parameters at full schema coverage and no output schema, the description fills the main remaining gap by enumerating the retrievable fields and flagging the getWritingGuidelines prerequisite. It is nearly complete for a retrieval tool, though it leaves the read-versus-write boundary unclear relative to what the schema actually accepts.

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 enumerating the collection's fields (alt, title, caption, description, aiAutofillStatus, poster, copyrightHolder, copyrightLicense, copyrightUrl) with localized/enum/required notes, which directly informs how to build `select` and `where` filters. It also explains the semantic role of `id` for later references in upload-fields, adding meaning beyond the schema's 'specific document ID to retrieve.'

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

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

The opening names the resource (content images, stock + uploads) but never cleanly states the operation this tool performs; the sentence 'MCP capabilities: find, update, delete' folds three operations into one description even though the input schema only supports retrieval. The resource is distinguishable from siblings like findPosts or findFaqs, but an agent scanning for a read tool has to infer that findMedia is the list/get operation.

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?

There is real routing guidance — 'Use `id` when referencing in upload-fields' and 'Before writing public text here, call getWritingGuidelines with this collection and the locale' — which tells the agent about a prerequisite sibling call. However, there is no statement of when to use findMedia versus alternatives, no exclusion of cases, and no mention of when the update/delete capabilities it advertises are actually reachable.

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?

No annotations are provided, so the description carries the full burden; it does disclose draft-table behavior and public read access, which is useful. However it says this tool's MCP capabilities include create/update/delete and warns about permanent deletes, which contradicts the find-only schema and can mislead an agent about side effects; pagination and return behavior are also absent.

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 very long for a find operation and is not front-loaded around listing/retrieving pages; it opens with block lookup and expands into publishing, field lists, and 39 layout blocks. Those details may belong to write tools but are waste here.

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-param find tool with no output schema or annotations, the description should focus on read behavior and response expectations, but instead it is dominated by write/publish/delete guidance. It provides some draft and public-read context, yet is not complete enough about how findPages returns or paginates results.

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 a useful semantic note for draft (without draft:true only published main-table state) and some locale/localization context. It does not add much for where/select/depth/sort beyond the schema.

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

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

The opening identifies the resource (editor-curated marketing pages) but never states a find/list verb up front; the only explicit 'find' appears inside a list of MCP capabilities that also claims create/update/delete. That muddles whether findPages is read-only and fails to distinguish it from sibling findX collection 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?

Most usage guidance is for writing/publishing (draft status, schedulePost, homepage slug, menus, getWritingGuidelines) rather than for when to call findPages versus findPosts/findFaqs/etc. The one find-specific rule—draft:true vs published state—is useful but does not give explicit when/when-not guidance.

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

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

With no annotations, the description still discloses meaningful behavior: draft versus published querying, public read availability, the permanent nature of deletes, and the distinction between internal author and public author semantics. It could be clearer that this tool itself is read-only, since listing 'find, create, update, delete' as MCP capabilities risks confusing the tool's actual scope.

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 a long wall of text that front-loads authoring and publishing semantics rather than the find operation. Many sentences concern create/update/delete and field definitions that are not parameters of this tool, so a substantial portion does not earn its place for findPosts.

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 read tool with no output schema and no annotations, the description gives useful collection context, field names, draft behavior, and public-read status. However, it does not describe the return shape or find-specific pagination/filtering behavior, and it spends much of its length on unrelated mutation and authoring details.

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 parameter definitions already carry most of the burden. The description adds useful meaning for the draft parameter by explaining that omitting draft:true returns only the published main-table state, but it does not add semantics for the other parameters such as id, page, sort, where, select, or limit.

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

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

The description identifies the resource as 'Blog-style articles' and mentions 'find' among the collection's MCP capabilities, but it never clearly states up front that findPosts retrieves or lists posts. It also does not distinguish the tool from sibling find tools such as findPages beyond the resource type, and much of the text is about create/update/delete behavior rather than the find operation.

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?

There is no explicit guidance on when to use findPosts versus findPages, findFaqs, or the other find siblings. The only find-specific usage note is the draft behavior ('a find WITHOUT draft:true returns the published main-table state only'); most other guidance concerns authoring, scheduling, and writing guidelines rather than when to call this tool.

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

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

With no annotations, the description carries the full burden and does disclose real behavior: drafts excluded, public read access, auto-generated slug when slug is omitted. However, the prominent '⚠ delete is PERMANENT' warning and the find/create/update/delete capability list describe capabilities this finder does not perform, which risks misleading an agent about what calling findTags actually does or can destroy.

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 leading sentence about the resource is well front-loaded, but the rest is a dense run of collection-level boilerplate (capability list, delete warning, writing-guideline workflow) that is not scoped to a read operation. Nothing is filler at the collection level, yet much of it does not earn a place in a finder's description.

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

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

For a 10-parameter, 0-required read tool with no annotations and no output schema, the description supplies the field vocabulary, default behavior (drafts excluded), access model, and a prerequisite call. Pagination interaction and how locale/depth behave for this flat collection are left to the schema, which is acceptable given 100% coverage.

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 earns more by correcting a real trap: the schema's own examples for `where`/`select`/`sort` reference "title", while the description states the field is `name` and lists the actual fields (name, slug, usageCount). That mapping is exactly the added meaning beyond the schema this dimension rewards.

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

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

The description identifies the resource precisely ("Flat keyword-tags for posts

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

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

It provides useful context — drafts are not returned, public reads go through /api/agents — and an explicit prerequisite workflow: call getWritingGuidelines before writing public text. But that guidance targets a different phase of work than finding tags; there is no statement about when to use findTags versus doing something else, or what happens with no filters. Usage is implied rather than directed.

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?

No annotations are provided, so the description carries the full burden, and it does disclose genuinely non-obvious behavior: `style` and `searchText` are redacted in find responses, draft:true switches to the versions table, and public reads are exposed via /api/agents. But it spends substantial space on a hard-delete warning and create/update/delete capabilities that findTeam does not expose, and never describes pagination or response shape.

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 text is a content-model dump rather than a tool description: field lists, URL routing rules, JSON-LD wiring, and SEO/meta groupings crowd out the actual operation. The most important operational facts (redaction, draft behavior) are buried mid-paragraph rather than front-loaded.

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?

It is rich on collection semantics—localization, redaction, draft state, author linkage—which compensates for the absence of annotations. With 10 parameters and no output schema, though, it never explains what a findTeam response looks like, how populated relationships (depth) appear, or pagination totals, leaving operational gaps.

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 meaning for `draft` (versions vs. published main table) and `locale` (localized field resolution), but says nothing about `depth` relationship population, `where` filtering, or `sort` usage 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 opening 'Team members / people (Person profiles)' identifies the resource but never states the operation this tool performs; the only verb-adjacent instruction—'use the `find` tool to list members with their `id`'—points at a sibling rather than describing findTeam. It also advertises 'MCP capabilities: find, create, update, delete', which overstates the scope of a read-only retrieval tool and muddies what findTeam actually does.

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?

Useful conditional guidance exists: draft:true is needed to see versioned state, and `style` must be read via getPersona(<id>) because it is redacted here. However there is no guidance on when to choose findTeam over findPosts/findPages/findTags, and the 'call getWritingGuidelines before writing public text' instruction is irrelevant to a read operation.

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 no annotations, the description carries the burden well: it discloses draft behavior, that a find without `draft:true` returns only the published main-table state, public read access via `/api/agents`, and the permanent nature of deletes. It does not describe read-side pagination or authentication details, but the core behavioral traits are covered.

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 and organized, but it is long and includes write/delete and field-requirement details that are not directly needed to invoke a find tool. Those details serve the collection documentation but reduce focus for this specific operation.

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 no annotations and no output schema, the description supplies useful collection context: fields, required/localized semantics, draft workflow, public read behavior, and writing-guideline routing. It stops short of describing the find response envelope or pagination metadata, but it is largely complete for selecting and calling this query 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 input schema already documents all 10 query parameters at 100% coverage, so the baseline is 3. The description adds some meaning around the `draft` parameter and `_status` filtering, but it does not meaningfully explain the other query parameters beyond what the schema provides.

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

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

The description identifies the resource clearly as customer quotes in the testimonials collection for testimonials-block use, which distinguishes it from sibling find* tools for other collections. It is not quite a crisp verb-first statement, and it also lists create/update/delete capabilities, which slightly muddies whether this tool itself is only for finding.

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

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

It gives clear usage context for testimonials-block, explains the published/draft behavior, says to use `_status:"published"` to go live, and routes scheduling to `schedulePost`. It does not explicitly name alternatives or exclusions among sibling find* tools, so it falls 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?

With no annotations, the description carries the full burden and does well: it discloses that the response is INTERNAL guidance, that house rules must be followed but never stated, that fixed terms stay unchanged across languages, and that taken keywords must not be reused. It does not mention permission requirements, error behavior, or rate limits, which keeps it short of a 5.

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

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

The imperative 'CALL THIS FIRST' is front-loaded, which is correct for a prerequisite tool, and the enumeration of returned brief contents earns its place given there is no output schema. It is dense but not padded; a slight trim of the long return-value list could improve it.

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 prerequisite/guidance tool with no output schema, the description fully explains what will be returned and the confidentiality constraint, so an agent knows both what to expect and how to treat the result. Nothing essential to 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 100%, so baseline is 3, but the description adds real meaning: it explains that `topic` prioritizes related taken keywords, that `locale` should be re-called per locale, and how `teamAuthor` injects a person's voice. These go beyond the schema's own wording.

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 (retrieve the writing brief/guidelines) and enumerates exactly what comes back: brand voice, house rules, fixed terms, locale rules, placeholders, author voice, SEO rules, taken keywords, and field-level writing guidance. This clearly distinguishes it from the find*/report* siblings, which retrieve or flag content rather than supply writing guidance.

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 'CALL THIS FIRST before you write or rewrite ANY public text' and specifies cadence 'once per task and target collection/locale.' It also spells out the condition for re-invoking per locale and instructs passing `topic` so relevant taken keywords rank first.

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 no annotations, the description carries the full burden and does well: it discloses that a human reviews every report and that nothing changes automatically, which tells the agent the effect is asynchronous and non-destructive. It does not describe what the agent gets back on submission (confirmation, ticket id, or nothing), which is the remaining behavioral gap for a write tool.

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

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

Four short sentences, front-loaded with purpose, then the exclusion, then the behavioral expectation, then the operational advice. Each sentence carries distinct information; nothing is repeated.

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-parameter submission tool with no output schema and no annotations, the description covers purpose, exclusions, human review, and how to phrase the report. It is nearly complete; only the post-submission outcome (what the caller observes after reporting) is unaddressed.

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 enum values for `kind` and the meaning of `where` and `message` are already documented. The description restates the essentials ("name the page (`where`) and what would be correct"), which reinforces good usage but adds little beyond the schema text. 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: report missing, wrong or outdated content to the site operator. It also carves out a neighboring domain ("Not for security vulnerabilities"), which is essential given that every sibling tool is a read/discovery tool (findPages, findFaqs, etc.) and this is the only submission route.

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 — a wrong, outdated or missing fact, a broken or misleading statement, or a coverage gap a visitor would expect — and names an exclusion (security vulnerabilities). It also gives a quantity convention ("one clear report per issue") that prevents the agent from bundling or spraying reports.

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