btlabs Core

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

With no annotations provided, the description carries the full burden and discloses substantial behavior: public read access via /api/agents/global, human-curated SSoT update policy, localized-field write constraints, and the need to resolve upload IDs separately. It also explains that fields carry editor descriptions accessible via getResourceSchema. This is rich behavioral context for a read 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?

The description is front-loaded with the tool's purpose but is very long and includes an exhaustive field list with types that may duplicate what getResourceSchema provides. While it is structured with separators, several sentences could be trimmed without losing essential guidance.

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

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

Given the complexity of a branding singleton with many fields, no annotations, and no output schema, the description provides a complete picture: what the resource contains, how to use it for content and image decisions, how to resolve upload IDs, and what the update policy is. Nothing critical for correct invocation 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 four input parameters (depth, locale, select, fallbackLocale) are fully documented in the schema. The description does not add any syntax or meaning beyond what the schema provides for these parameters. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Find a Payload global singleton configuration.' It then identifies the resource as the brand identity singleton, which clearly distinguishes it from sibling tools like findFaqs, findMedia, and findPages. An agent can tell it apart 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 usage direction: 'READ FIRST when drafting content or answering about the business' and 'read it BEFORE generating images.' It also points to alternatives for resolving upload IDs via 'brand' find/get. However, it does not explicitly state when not to use it or compare against the other find 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?

With no annotations provided, the description bears the full burden and does an excellent job. It discloses draft behavior (find without draft:true returns only published state), public read access via /api/agents, the full MCP capability set (find, create, update, delete), and a strong warning that delete is hard-delete not caught by the admin Trash. It also notes field constraints like localization and character limits. No contradictions with annotations (none exist).

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 single, dense run-on paragraph of about 200 words, mixing resource fields, workflow notes, and warnings without clear segmentation. It front-loads with 'FAQ entries' but then cascades into many semicolon-separated points that are hard to parse quickly. It could be broken into bullet points or sections for better scannability. It is not concisely structured.

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

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

Given there is no output schema, the description should clarify return shape or pagination behavior. While it covers many operational aspects (drafts, permissions, delete), it does not describe the response format (e.g., array of documents, fields included) or how pagination parameters interact with results. Since the schema covers parameter semantics, the missing piece is the output contract. The description is not fully complete for a complex find tool with 10 parameters.

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 has 100% description coverage for all 10 parameters, providing baseline explanations for each. The description adds meaningful context for the `draft` parameter (explaining that without draft:true it returns only the published state) and implicitly ties `where` filtering to the field descriptions. However, it does not add significant detail for other parameters such as `page`, `limit`, or `sort`, which remain schema-defined. This meets the baseline but does not elevate beyond it.

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

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

The description clearly identifies the resource as 'FAQ entries' and elaborates on the exact fields (question, answer, categories) and its usage in the /faq system page and faqBlock. It also names the collection ('faqs') and lists the MCP capabilities. This is specific enough to distinguish it from siblings like findPages or findPosts without ambiguity.

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

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

The description provides practical usage context: it explains the draft/publish workflow, the need to use `_status:"published"` for live content, the existence of the `schedulePost` tool for future dates, and the permanent delete warning. However, it does not explicitly state when to use this tool versus alternative find tools (e.g., 'use for FAQ content only'), nor does it compare to siblings. This is adequate but not explicit 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?

With no annotations, the description carries full responsibility, and it does excellently: it discloses required fields (title, shortDefinition), max lengths, drafts behavior ('find WITHOUT draft:true returns published main-table state only'), public access via /api/agents, MCP capabilities, and a critical warning that delete is permanent and bypasses the admin Trash. This is comprehensive behavioral disclosure.

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 single dense paragraph covering many aspects: fields, constraints, drafts, public access, MCP capabilities, and a deletion warning. It is not well-structured with sections or bullet points, and while each sentence contributes information, the flow is somewhat jumbled. It is informative but not concise in format.

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 find tool with no output schema, the description provides rich context: it explains field constraints, locale handling, autolinking behavior, draft querying, and permanent deletion. It covers everything an agent needs to call the tool correctly, though it could mention pagination defaults (but schema already does). The completeness is high given the tool's complexity.

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 parameters (id, page, sort, depth, draft, limit, where, locale, select, fallbackLocale) have descriptions in the schema. The tool description adds no additional meaning to these parameters; it focuses on glossary field constraints, not query parameters. Baseline 3 applies since the schema already documents them.

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

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

The description clearly states the tool finds glossary entries ('Public glossary of terms.') and explains key fields and behaviors. While it doesn't explicitly contrast with sibling find tools, the resource type is unambiguous. It's specific enough to distinguish from findBrand, findPosts, etc., by the glossary context.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It mentions features like drafts and public read, but does not say 'use this when you need glossary terms' or exclude other tools. The usage context is implied by the name, but the dimension requires explicit 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 provided, the description carries full responsibility for behavioral disclosure. It thoroughly discloses that MCP can READ, UPDATE, and DELETE, that DELETE is permanent and bypasses the admin Trash, that drafts are not supported, that public read is available via /api/agents, and it lists the exact fields and enums. This is far beyond what the schema alone provides.

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 dense, unstructured block of text covering multiple concerns: purpose, capabilities, delete warnings, field lists, and access notes. It is not front-loaded in a scannable way; the key purpose statement is followed by a long enumeration of capabilities and fields. While information-dense, it lacks organizational structure and is overly verbose for a find 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?

Given the tool has 10 parameters, no output schema, and no annotations, the description provides substantial context: the collection name, capabilities, delete permanence, draft handling, public read access, and field definitions. It does not describe the response structure, but with no output schema that is not required. Overall, an agent has enough information to call the tool 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 all 10 parameters are already documented with descriptions in the schema. The description adds minimal extra meaning for parameters: it clarifies that drafts are not supported (relevant to the 'draft' parameter) and suggests using 'id' in upload-fields, but does not enrich the understanding of other parameters beyond the schema.

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

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

The description clearly identifies the tool as operating on content images (stock + uploads) within the media collection, and it distinguishes itself from the sibling find* tools by being the only one that mentions 'media collection' and 'Content images'. It states the verb 'find' as a capability, making the purpose unambiguous.

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

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

The description does not explicitly state when to use this tool versus the other find* siblings, though the media-specific focus implies it for media queries. It does provide a usage note for a different tool ('binaries come via the addMediaFromUrl tool') and clarifies that drafts are not supported, but no direct alternatives or exclusions are mentioned.

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 discloses important behavioral traits: the draft/published main-table behavior, public read access, and that delete is permanent (though that's unrelated to find). It also notes that systemPageKey is read-only in MCP, which could affect query expectations. These disclosures go beyond the schema and help the agent understand the tool's behavior, though it doesn't cover every aspect like rate limits or response size.

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 excessively long and covers the entire pages collection—creation workflow, scheduling, deletion warnings, field lists, and 44 layout block names—far more than a find tool needs. It is not front-loaded for the find operation; the most relevant behavior (drafts) appears mid-paragraph. The structure is a dense stream of text without headers, making it hard to parse for an agent focused on retrieval.

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 find tool with 10 parameters, the description provides some useful context: localizable fields, draft/published semantics, systemPageKey read-only, and the existence of layout blocks (which could be filter targets). However, it does not explain how to use the where clause effectively, any pagination quirks, or the relationship with menus. The schema covers parameter syntax, but the description lacks practical query examples. Overall, it is adequate but not thorough for a complex find operation.

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 all parameters. The description adds value only to the draft parameter by explaining its behavioral impact (published vs. draft states). It does not add meaning to other parameters like where, sort, or select. Since baseline for high coverage is 3 and it adds a bit, it stays at 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 opens with 'Editor-curated marketing pages,' which clearly identifies the resource type (marketing pages) and distinguishes it from sibling find tools for other collections (brands, FAQs, posts, etc.). The name 'findPages' and the mention of 'MCP capabilities: find, create, update, delete' make the purpose evident. However, it never explicitly states 'This tool retrieves pages' as a primary directive, relying on the name and context.

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

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

The description provides clear context for use: it states the draft behavior ('a find WITHOUT draft:true returns the published main-table state only'), which is a key usage condition. It also gives guidance like 'Call listAvailableBlocks first' (though that's for creation, not find) and mentions the public read via /api/agents. It does not explicitly name alternatives or exclusions, but the resource clarity is sufficient.

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 of behavioral disclosure, and it does provide meaningful context: draft behavior, public-read availability, redacted searchText, and permanent delete warnings. However, much of this context is irrelevant to a find tool (author modes, scheduling, hard-delete), and the 'MCP capabilities: find, create, update, delete' line could mislead an agent into thinking this tool mutates 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?

The description is a dense, sprawling block that mixes find behavior with author-mode configuration, scheduling instructions, and delete warnings. Valuable information is buried among irrelevant mutation guidance. It is not appropriately sized or front-loaded for a retrieval 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?

The description provides substantial collection-level context, including draft behavior, public read, localization, and a full field list. However, it lacks an explicit statement of what the tool returns, and it omits the core purpose in favor of tangential creation/publishing details. For a find tool with no output schema, the missing return-value description is a notable gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by clarifying the `draft` parameter's effect ('a find WITHOUT draft:true returns the published main-table state only') and by enumerating the collection fields, which helps agents construct `where`, `select`, and `limit` queries with correct field names and types.

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 'Blog-style articles' rather than a clear verb like 'Find/retrieve posts.' It never explicitly states that this tool retrieves posts, and the mention of 'MCP capabilities: find, create, update, delete' blurs whether this tool performs mutations. The resource is identifiable, but the action is only implied by the tool name and schema, not the description.

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 does not clearly state when to use findPosts versus sibling find tools or mutation tools. It references other tools like the `team` find tool and `schedulePost`, but those are tangential to retrieval. The only retrieval-specific guidance is the draft behavior ('a find WITHOUT draft:true returns the published main-table state only'), which is useful but not a complete usage guideline.

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 provided, the description carries the full burden. It discloses that drafts are not returned, that the field is `name` not `title`, and warns that deletes are permanent (though that's about MCP capabilities, not this read operation). This adds valuable context beyond the schema.

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 organized with semicolons and a warning, front-loading the core purpose. It's not overly verbose and each piece of information serves a purpose.

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

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

For a simple find operation, the description covers key behaviors (drafts excluded, field naming) but does not explicitly describe the response structure or what fields are returned, relying on the schema for parameters. Since there is no output schema, this leaves some ambiguity about the return format.

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

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

The schema already describes all 10 parameters with 100% coverage, so the description does not need to add parameter details. It does clarify domain-specific field names (name vs title) but that is not about the parameters themselves, so the baseline score of 3 is appropriate.

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

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

The description states the tool's purpose clearly: it retrieves flat keyword-tags for posts, and explicitly notes the `name` field instead of `title`, distinguishing it from other finders. It also mentions the collection, making it unambiguous which resource it targets.

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

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

The description provides context about drafts ('Drafts: no') and public read access, but does not explicitly compare to sibling tools or state when to use this tool instead of others. Usage is implied by the tool name and resource, but no explicit routing 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 provided, the description carries the full burden of behavioral disclosure. It thoroughly covers: drafts not returned without draft:true, style being redacted in find responses, public read via /api/agents, permanent deletion for the delete operation, and the fact that order is used by the team block. These are critical behavioral traits that an agent needs to know.

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 and dense, covering extensive field details and behaviors. While comprehensive, it could be better structured and more concise. The core purpose is front-loaded, but the volume of information may overwhelm an agent. It earns a 3 because it's thorough but not well-organized for quick consumption.

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 find tool with no output schema, the description provides all necessary context: entity definition, field types, localization, required fields, redaction, draft behavior, public read access, capabilities, and cross-references to posts and getPersona. An agent has everything needed to correctly use the find tool and interpret 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 all parameters are already described in the input schema. The description adds minimal parameter-specific meaning beyond what's in the schema; it only touches on draft:true behavior and the redaction of style in responses, which are response-level details rather than parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly identifies the resource as 'Team members / people (Person profiles)' and explains its purpose as a collection that can be listed via the find tool. It distinguishes the entity from siblings by describing its specific fields and behaviors (e.g., no /team index page, linking to posts). However, it doesn't explicitly state that the tool's function is to retrieve team members, but that's implied.

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?

Provides clear usage guidance: use the find tool to list members with their id (needed for post's teamAuthor), and mentions that draft:true is required to see drafts. It also notes that style is redacted and to use getPersona for the real value. While it doesn't compare against sibling find tools, each collection is distinct, so usage is reasonably 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?

With no annotations provided, the description carries the full transparency burden and does this well: it discloses permanent hard-delete, draft visibility and aggregate-rating exclusion, public read access, and the published-only behavior of find without draft:true. This is exactly the kind of behavioral context 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 and front-loads the purpose, but it is written as a long run-on with redundant mentions of the testimonials collection and draft behavior. The content is relevant, but it would be easier to parse with bullets or shorter sentences.

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 tool with no annotations and no output schema, the description provides substantial context: required fields, draft lifecycle, scheduling via schedulePost, public read path, and a critical delete warning. It does not describe the response envelope or return format, but the schema already covers pagination and locale 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 baseline is 3. The description adds domain-level meaning (author+quote required, rating 1-5, featured boolean, publishedAt) that could inform where/select clauses, but it does not add value to the generic parameters like sort, depth, or locale beyond what the schema already states.

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

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

The opening phrase 'Customer quotes for use in testimonials-block' clearly identifies the resource and domain, and the field list distinguishes this from sibling find* tools. It lacks an explicit verb like 'List' or 'Retrieve', but the intent is unmistakable.

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 implies usage through the testimonials collection and published/draft workflow, and mentions schedulePost as a related alternative for scheduling. However, it does not explicitly state when to choose this tool over siblings like findPosts or findPages, nor does it provide when-not-to-use guidance.

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