Nokbase

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

Annotations already declare readOnly=false, destructive=false, openWorld=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: the created brand is empty, and a plan limit produces an upgrade link rather than an error — that detail materially changes how an agent should interpret a response. It stops short of stating what identifier or payload is returned or whether duplicate names are permitted.

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 tight sentences, front-loaded with the usage condition, then scope, then the required field, then the exclusion and the edge case. No filler and nothing buried.

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

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

For a three-parameter create tool with no output schema, the description covers trigger, scope, required input, the sibling it must not be confused with, and the failure mode a caller will actually encounter. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, and the schema's own text ('as the user says it', 'if the user has said') already conveys the important semantics. The description only restates that `name` is required and says nothing about about/audience, so it fails to beat the baseline set by a fully documented schema.

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

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

States a specific verb+resource ('Creates an empty brand under their account') and immediately scopes what the result is — an empty shell to be filled in later. It explicitly separates itself from update_brand, so an agent can route without reading 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 an explicit trigger ('only when the user asks to create, add or set up a new brand, business, client or project') and an explicit exclusion with the correct alternative ('Do not use it to rename or change a brand that already exists; use update_brand'). Both when and when-not are covered.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the hazard profile is known. The description adds real value beyond that: it specifies the blast radius (only the one item, in both library and dashboard), the confirmation gate, and the entity types explicitly out of reach. It stops short of stating that the deletion is permanent/irreversible, which is the main residual gap.

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

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

Three sentences, each doing distinct work: eligibility/confirmation gate first, effect second, negative scoping third. No repetition of the name or title and 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?

For a destructive tool with full schema coverage, strong annotations, and no output schema, the description covers scope, confirmation, effect, and out-of-scope entities. An agent has everything needed to decide whether to call it and what to expect, with irreversibility being the only minor omission.

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 slug, brand, and confirm are all documented in the schema itself, which sets the baseline at 3. The description only implicitly reinforces the confirm parameter ('only after they confirm') and says nothing about slug formatting or the brand-defaulting behavior, so it adds little parameter-level meaning over 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 names a specific verb (remove/delete) and a tightly scoped resource: one specific saved Prompt or Skill. It also states where the removal takes effect (library and dashboard), so an agent can distinguish it from update_library_item or list_library without inspecting 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 an explicit precondition ('only when the user explicitly asks... and only after they confirm') plus explicit exclusions ('cannot delete facts, sessions, brands or the user's account... never use it for requests to delete an account or all data'). Both the when and the when-not are stated outright, leaving nothing 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the description doesn't need to restate safety. It does add genuinely new context: the generation is performed by Nokbase's own model and the brand context is injected as instructions, which tells the agent what it is actually invoking. It stops short of describing latency, cost, or what the returned text looks like, so it isn't a full 5.

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

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

Three sentences, zero waste. The core capability leads, and the routing constraint plus alternative follow immediately, so the most decision-relevant information is 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?

For a single-call text generation tool with fully documented parameters and a complete annotation set, the description covers what the agent needs to choose and invoke it. No output schema exists, but describing return values is unnecessary for an obvious text-generation result, leaving only minor gaps around model behavior specifics.

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

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

Schema description coverage is 100% and each of the three parameters (format, length, prompt) already carries its own description with defaults and token ranges. The description adds nothing about parameter behavior beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Generates text with Nokbase's own model') and clarifies the mechanism ('using the brand context as its instructions'). It also implicitly distinguishes itself from get_brand_context, which is named as the sibling used for the other path.

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 names the when: only when the user explicitly asks Nokbase to generate the text. Explicitly names the when-not and alternative: 'When you are writing the content yourself, which is the usual case, call get_brand_context and write it directly instead.' This is about as unambiguous as routing guidance gets.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context the annotations don't: the call mints a 'fresh download link' rather than returning a static URL. It stops short of saying whether the link expires or how failures look, keeping it below 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?

Two sentences, both front-loaded with the decision rule first and the exclusion second. No filler, no restating of the tool name or schema.

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

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

For a single-parameter read tool with no output schema, the description covers when to call it, what it returns, and what not to use it for. The only meaningful omission is the lifetime/expiry behavior of the 'fresh' download link, which matters for how the agent sequences downstream use.

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

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

Schema coverage is 100% and the single parameter is typed and documented as 'The asset UUID', so the schema handles the mechanics. The description still adds provenance value by telling the agent where to obtain that ID (list_assets).

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 ('get_asset') and names both outputs: the file's details and a fresh download link. It also explicitly distinguishes itself from the browsing sibling list_assets, so an agent can pick it 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 an explicit precondition ('when you already have an asset's ID (from list_assets)'), an exclusion ('Do not use it to browse files'), and names the alternative tool to use instead. Nothing 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 readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds useful behavioral context: it returns the same data as get_brand_context but in raw JSON, and notes that get_brand_context additionally includes saved facts and assets. It doesn't cover rate limits or pagination, but for a read-only getter this is strong added value.

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 with zero waste. The main purpose and distinguishing detail come first, followed by the routing guidance to the alternative 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?

There is no output schema, so the description must convey return value information. It does so by stating that the tool returns the same brand identity, voice, and visual data as get_brand_context, with examples like hex colour and tone attributes. This is adequate for an agent to decide whether to call it, though a more explicit list of returned fields would make it fully complete.

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 the single 'brand' parameter, including guidance to ask the user if unclear. The description does not add any meaning about the parameter beyond what the schema already provides, 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 a specific verb ("Returns") and resource ("brand identity, voice and visual data"), and explicitly distinguishes the tool from its sibling get_brand_context by noting it returns raw JSON fields for programmatic use. An agent can immediately understand what this tool does and how it differs.

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 guidance on when to use this tool (programmatic use, e.g., reading a hex colour or tone attributes) and when to prefer the alternative ("Prefer get_brand_context for any writing task"). Both the positive and negative conditions are clearly stated.

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

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

The annotations already establish that this is a safe read operation (readOnlyHint true, destructiveHint false, openWorldHint false). The description adds useful behavioral context beyond annotations by stating the return format is markdown and enumerating what sections are included, including latest-session notes when available.

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 key instruction ('Use this FIRST') and remains reasonably tight. The second sentence slightly repeats the first by adding an example, but the overall structure is clear and efficient.

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

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

For a simple read-only tool with one optional schema-documented parameter and no output schema, the description is complete enough: it explains when to call it, what it returns, and how to use the returned context. No critical agent-facing information is missing.

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

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

There is one optional parameter and schema description coverage is 100%, so the schema already explains the brand-name/default-brand behavior. The description does not add parameter-specific details, which is acceptable given the high schema coverage baseline.

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

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

The description clearly states the resource and scope: it returns the user's full brand context for writing/copy/brand-voice needs, including identity, voice/tone, visual identity, assets, facts, and latest-session notes. It is specific about what it does, though it does not explicitly distinguish itself from siblings such as get_brand or list_brands.

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 a strong explicit trigger ('Use this FIRST whenever the user asks for writing, copy...') and covers related phrasing like 'use my Nokbase context'. It does not name when-not-to-use cases or explicit alternatives, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description still adds value by disclosing the shape of the returned content — accomplishments, decisions, next steps — which matters because no output schema exists. It does not cover edge cases such as what happens when no prior session exists, keeping 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?

Three sentences, front-loaded with the usage trigger before the return description and the disambiguation. Every clause carries distinct information; nothing is repeated from the title or annotations.

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

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

With zero parameters and no output schema, the description must carry both selection guidance and return semantics, and it does both. An agent can decide when to call it and knows what it will receive without further information.

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

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

The tool takes no parameters, so the baseline is 4. The description correctly implies no arguments are needed to obtain the latest session, matching the empty schema.

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

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

States a specific verb and resource ('Returns the most recent session log') and enumerates the payload ('what was accomplished, decisions made and next steps'). It explicitly distinguishes itself from get_brand_context and list_sessions, 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?

Gives concrete trigger phrases ('pick up where they left off', 'what they were working on last time', 'refers to an earlier conversation') plus explicit exclusions pointing to get_brand_context and list_sessions. Both the when and the when-not are covered with named alternatives.

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

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

Annotations already establish it is a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), yet the description adds genuinely new behavioural context: the return content is delimited by PROMPT markers and must be executed verbatim without rewriting, summarising or improving. That is valuable handling guidance beyond the annotations, though it says nothing about failure modes when the slug does not resolve.

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 usage trigger is front-loaded in the first sentence and every sentence carries a distinct instruction (trigger, return, fallback, verbatim rule, exclusion). Slightly dense, but 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?

For a 2-parameter read-only fetch with full schema coverage and no output schema, the description covers the trigger, the return contract, the disambiguation path and the downstream handling rule. Nothing an agent needs in order to call it and use the result correctly is missing.

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

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

Schema coverage is 100%, so both slug and brand are fully documented in the schema, and the description re-states the slug lookup path only implicitly via the list_library reference. The brand parameter is never mentioned in the description, so it adds no meaning beyond the schema; 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?

It uses a specific verb and resource ("Loads a saved Prompt by slug and returns its exact text") and distinguishes itself from both list_library (unknown slug) and get_skill (saved Skills). An agent can route correctly without opening any schema.

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

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

It spells out the trigger (user asks to run, use or reuse a prompt saved earlier, possibly in a different AI tool), the fallback when the slug is unknown (call list_library first), and an explicit exclusion (not for Skills; use get_skill).

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond that: a Skill is guidance to act on and its steps should be applied to the task, which tells the agent how to treat the returned content. It stops short of describing error behavior, such as what happens with a nonexistent slug, which keeps it at 4.

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

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

Front-loaded with the usage trigger, then the mechanics, then the conceptual distinction from Prompt. Every sentence carries information an agent needs in order to choose correctly.

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

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

For a read-only, two-parameter, no-output-schema tool, the definition covers the trigger, the slug prerequisite, the fallback discovery path, and the Skill-versus-Prompt distinction. Nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both slug and brand are fully documented in the schema. The description reinforces slug discovery via list_library but says nothing about the brand parameter's default fallback or cross-brand behavior. Baseline 3 is correct given the schema does the heavy lifting.

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

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

States a specific verb and resource ('Loads a saved Skill by slug') and explicitly contrasts itself with get_prompt and list_library. An agent can distinguish it from every sibling without opening the schema.

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

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

Gives the trigger ('when the user asks to use or apply a skill'), a fallback for unknown slugs ('call list_library first'), and an explicit when-not ('do not use it for saved prompts; use get_prompt for those'). This is as complete as guidance gets.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that this returns the complete content of the source (every synced page/document), which is useful behavioral context about output volume, though it does not discuss result size limits or pagination for large sources.

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 short sentences, front-loaded with the use case and example, followed by the alternative routing and an explicit exclusion. Every sentence carries actionable information with 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 one required parameter, full schema coverage, and read-only annotations, the definition is nearly complete; it covers what is returned and how to obtain the ID. The only gap is guidance on volume or pagination when a source contains many documents, which matters for a 'read everything' tool, but no output schema exists and annotations carry the safety profile.

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 source_id parameter is already documented as a UUID obtained from list_sources. The description reinforces that provenance ('get the source ID from list_sources') but adds no format or syntax detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('returns every synced page or document from that source') and scopes it to one connected source. It explicitly distinguishes itself from search_knowledge and get_brand_context, so an agent can separate it from siblings without reading schemas.

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

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

Gives a concrete trigger ('full content of one connected source', with a user-phrase example), names the alternative for specific questions (search_knowledge), and explicitly excludes brand voice/identity in favor of get_brand_context. When-to-use, when-not-to-use, and alternative routing are all present.

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

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

Annotations already declare read-only, non-destructive, closed-world, so the safety profile is covered. The description still adds real value by disclosing that download links are short-lived — an important behavioral trait an agent would otherwise not know. It stops short of describing ordering, pagination beyond 'limit', or how expiry surfaces.

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 short sentences, front-loaded with the use trigger, then the capability, then the exclusion. No filler or repetition.

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 adequately conveys the return shape (list of assets with download links) and the optional filter. Minor gap: nothing about result ordering or what happens when no assets match, but 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 description coverage is 100% and both parameters are already documented with defaults and the type enum-ish list. The description only restates 'optionally filtered by type', adding no syntax or semantic detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists the brand's assets') plus a distinguishing behavioral detail (short-lived download links, optional type filter). It is immediately separable from get_asset (single file) and get_brand_context (identity).

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

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

Gives concrete use triggers ('user asks for their logos, images, documents or other brand files, or you need a file's download link') and an explicit non-use case routing to get_brand_context for brand voice/identity. Both when and when-not are spelled out.

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

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

Annotations already declare read-only, non-destructive, closed-world behavior. The description adds useful behavioral context beyond annotations: it marks the connection's default brand and reports how many more brands the plan allows, though it does not describe return shape or ordering.

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 primary use case, then explains what it returns, then gives an explicit exclusion. Every sentence adds distinct value with no wasted text.

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

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

For a zero-parameter read-only listing tool with no output schema, the description is complete enough. It explains what the tool returns and when to call it versus get_brand_context, leaving no critical gap for correct invocation.

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

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

The tool takes zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it appropriately focuses on usage and output behavior instead.

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 uses a specific verb and resource ('Lists the user's brands') and clearly distinguishes the tool from get_brand_context by stating it is not for brand details. It also adds scope details like default marking and plan-limit count.

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 triggering conditions: when the user asks which brands they have, or when checking the conversation's brand before saving. It also names the alternative for brand details, get_brand_context, making the routing decision unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so safety is covered; the description still adds useful return-shape context (two headings, newest first) and the downstream slug workflow. It omits volume limits or pagination behavior, 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?

Front-loaded with the use case and well ordered (trigger → contents → follow-up → exclusion). It is slightly longer than needed, with the 'word for word' aside and exclusion sentence adding length, but no sentence is truly waste.

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

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

No output schema exists, and the description compensates by describing the return structure (Prompts/Skills headings, newest-first ordering) and what to do with the slugs. Nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the schema itself explains both 'kind' and 'brand' plus the default-brand fallback. The description adds no parameter-level detail beyond referencing 'slug' from the returned items, so the schema carries the load.

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

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

States a specific verb and resource ('Lists everything saved in the user's Nokbase library') and enumerates the two subtypes it returns, Prompts vs Skills. An agent can distinguish it from get_prompt/get_skill and from brand-context tools 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 an explicit trigger ('when the user asks which prompts or skills they have saved, or wants to run or reuse one and you don't know its slug'), an explicit exclusion ('Do not use this for brand voice, identity or saved facts. Use get_brand_context'), and a follow-up routing step ('Then call get_prompt or get_skill with the slug').

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 and non-destructive, so the description doesn't need to restate safety. It adds real value by disclosing the shape of each returned log entry (summary, decisions, next steps) and that filtering is optional — important since there is no output schema. Minor gap: no mention of ordering (newest first?) or total volume.

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

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

Three sentences: trigger, behavior, then the disambiguation pointer. Every sentence carries information and the routing advice is placed last where it's easy to act on.

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

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

For a zero-required-parameter read tool with full schema coverage and annotations, this is nearly complete: it covers purpose, trigger, return content, filtering, and the alternative. The only missing detail an agent might want is ordering/pagination context for a list 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 coverage is 100% and the schema descriptions are richer than the prose (numeric range, clamping behavior, the full source enumeration). The description only echoes the source filter at a high level, adding nothing beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Lists recent session logs') plus the payload shape (summary, decisions, next steps) and the optional source filter. It explicitly distinguishes itself from get_latest_session, which is the main ambiguity among siblings.

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 concrete trigger example ('what did we decide in Cursor last week') and names the alternative tool with the exact condition that selects it ('to simply resume the most recent session'). Both the when-to-use and when-not paths are covered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the result surfaces sync state and per-source item counts, which is genuinely useful since there is no output schema. It stops short of describing read cost, ordering, or how unsynced or errored sources appear, so it is strong but not exhaustive.

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

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

Three sentences, front-loaded with the use case, followed by a one-line statement of what it returns and a one-line routing rule to a sibling. No restated name or filler, and each sentence carries distinct information.

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

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

For a zero-parameter read-only list tool, the description covers the trigger conditions, the exclusion, the routing alternative, and the shape of what comes back — compensating adequately for the absent output schema. Nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is empty and fully self-explanatory. Baseline applies with no compensating information needed.

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

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

States a specific verb and resource ('Lists connected sources') plus the exact attributes returned ('sync status and item counts'), and explicitly separates itself from search_knowledge by stating it is not for finding content. An agent can distinguish it from the other list_* siblings without opening any schema.

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

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

Gives the triggering user intents directly ('asks which Notion pages or Google Drive folders are connected, whether they have synced, or how many items each holds'), then adds an explicit exclusion ('Do not use it to find content') and names the correct alternative, search_knowledge. This is the full when/when-not/alternative pattern.

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

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

Beyond the annotations, it discloses a critical non-obvious behavior: the tool rewrites content into a summary and never keeps exact wording, so it warns against use when wording matters. It also states 'It only saves,' clarifying no read/return of facts, which annotations do not 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?

Front-loaded with the purpose and positive triggers before the exclusions, and nearly every sentence carries routing or behavioral information. It is slightly long and the 'It is for a sentence or two of standing knowledge' clause partly restates the opening, costing a little economy.

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 no-output-schema write tool, the definition covers purpose, exclusions, alternatives, and the lossy-summarization behavior thoroughly. It does not state what a successful call returns (e.g., confirmation or category assigned), which is the only 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 brand, content and category are already fully documented in the schema. The description adds a useful content-length constraint ('a sentence or two') but does not otherwise elaborate on parameter usage or formats, so the baseline 3 applies.

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

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

States a specific verb and resource ('Saves a short fact about the user's company, brand, product, audience or how they work... to their Nokbase vault') and scopes it tightly to short standing knowledge. It explicitly distinguishes itself from siblings save_prompt and get_brand_context, 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?

Gives explicit when-to-use triggers ('when the user asks to remember, note or save such a fact') with example utterances, and explicit when-not-to-use rules with a named alternative ('Do NOT use it for a document... use save_prompt'). It also names get_brand_context for the read case.

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=false, destructiveHint=false and openWorldHint=false, so the write/safety profile is covered. The description adds genuinely new context—deprecation status and behavioral equivalence to another tool—without contradicting anything, though it says nothing about persistence scope or side effects on existing facts.

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 short sentences, front-loaded with the identity of the tool and the routing instruction, with zero redundant restatement of the schema.

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

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

For a deprecated alias with fully documented parameters and no output schema, the description provides everything an agent needs to decide whether to call it. It could add what happens if both tools are used in one session, but nothing essential is missing.

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

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

Schema description coverage is 100%: brand, content and category are all documented in the schema with examples and fallback behavior. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description identifies the tool precisely as a legacy alias of remember_brand_fact and states it behaves identically, which lets an agent place it relative to a named sibling. The only shortfall is that the actual operation (saving brand knowledge) is only inferable from the schema, not stated in prose.

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

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

It gives an explicit prohibition ('Do not use unless remember_brand_fact is unavailable') and an explicit condition under which it exists (older cached tool lists). That is a textbook when-not-to-use plus named alternative.

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

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

Beyond the annotations, the description explains important behavior: optional fields are auto-generated, the text must be stored verbatim without cleanup, and this tool is the exclusive verbatim save path. These details directly affect how the agent should invoke the tool and guard against incorrect use.

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 primary trigger and purpose, followed by the exclusivity claim, required-field guidance, and the key verbatim/alternative-use caution. Each sentence contributes useful selection or invocation guidance without unnecessary digressions.

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 thoroughly covers when to call the tool, required and optional fields, verbatim storage behavior, and a relevant alternative to avoid. The main gap is that there is no output schema and the description does not explain what the tool returns after saving, though that is a minor omission for a save action.

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

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

Schema description coverage is 100%, so all six parameters are already well documented. The description reinforces that only prompt is required and that name, slug, and description can be omitted, but this largely repeats schema-level guidance rather than adding new parameter semantics.

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

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

The description clearly states that this tool saves prompt text for reuse and explicitly calls out that it is the only tool that preserves text word-for-word. It also distinguishes itself from remember_brand_fact, which compresses text, so an agent can confidently choose this tool over siblings.

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 trigger phrases and conditions for calling the tool, including cases where the user does not say 'prompt' explicitly. It also names a specific alternative not to use and explains why, and tells the agent not to pause to gather optional fields.

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 a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely new behavior: the newest session is injected into brand context for any AI, and at 5+ sessions recurring themes are extracted and the brand context is enriched. It does not say whether repeated calls create duplicate sessions or overwrite, which is the main residual 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?

Front-loaded with the invocation trigger, then what is stored, then the downstream effect, then the exclusion — a logical order with no filler. Every sentence carries distinct information an agent can act on.

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

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

For a 4-parameter, single-object write with no output schema, the description covers the trigger, the payload, the downstream consumption and the sibling boundary. It stops short of describing the call's return value (e.g., a session id the agent might want to reference later), which would round it out.

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 every parameter is already documented, and the description's mention of summary, decisions and next steps only restates what the schema says. The session_source parameter is never referenced in the description. Baseline 3 is appropriate since the schema carries the parameter burden.

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 (save/log a session) plus exactly what it writes: a summary of what was accomplished, key decisions and next steps. It explicitly contrasts with remember_brand_fact and, by implication, with the read-side siblings get_latest_session and list_sessions, so an agent can route correctly without opening a schema.

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

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

Gives an explicit trigger ('when the user asks to save or log this session, or wants the next conversation, in any AI tool, to pick up from here') and an explicit exclusion with the named alternative ('Do not use it for a standing brand fact; use remember_brand_fact for that'). Both the when and the when-not are present.

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=false, destructiveHint=false, openWorldHint=false), so the description adds genuine behavioral context instead: metadata fields are auto-generated, so the agent can call immediately without a clarification round-trip. It stops short of disclosing what happens on a duplicate slug or whether re-saving overwrites an existing skill.

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

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

Front-loaded with the invocation trigger, then the required-field fact, then the 'don't stall on metadata' instruction, then two routing sentences. Roughly seventy words with no filler and every sentence carrying a distinct decision the agent has to make.

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?

There is no output schema, so the description should ideally say what comes back on success or what a same-name save does; it doesn't. Everything an agent needs to decide whether and how to invoke the tool, including the brand-scoping fallback covered by the schema, is otherwise present.

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 every field including auto-derivation of name/slug is already documented in the schema. The description's 'Only `procedure` is required' and the auto-generation note largely restate the required array and the schema's own 'it's derived automatically' text, adding emphasis rather than new 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 (save) plus the resource (skill/workflow/repeatable method) and defines it in contrast to near-misses: a procedure to follow, 'not fixed text to run.' That negative definition lets an agent separate it from save_prompt and remember_brand_fact without opening any schema.

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

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

Gives explicit trigger conditions ('when the user asks to save a skill, a workflow, or a repeatable method'), explicit exclusions routed to named alternatives ('use save_prompt, not this' / 'use remember_brand_fact'), and an explicit anti-pattern ('Do not pause to ask the user for a name, slug, or description first'). This is the full when/when-not/alternative triad.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior the schema cannot express: it returns passages rather than whole documents, and returns empty when no sources are connected — a real failure mode an agent must anticipate. It does not describe ranking or result ordering, which keeps it from a 5.

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

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

Four short sentences, each doing distinct work: scope, positive use case, negative exclusion plus alternative, and empty-state behavior. The scope constraint is front-loaded and capitalized, so the most important caveat is read first.

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

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

For a two-parameter read-only search with no output schema, this covers everything the agent needs: what corpus is searched, what a result is, when not to call it, and what an empty response means. Nothing essential is missing.

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

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

Schema coverage is 100% and both parameters (query, limit with default 10) are already documented there. The description adds no query syntax, phrasing advice, or meaning for limit beyond what the schema states, so baseline 3 applies.

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

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

Specific verb+resource ("searches documents synced from connected sources") with an explicit scope limiter ("ONLY") and a stated return type ("matching passages"). It names concrete source systems (Notion pages, Google Drive files), which no sibling tool covers, so the agent can distinguish it from get_brand_context immediately.

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 positive trigger with examples (spec, meeting notes, policy), an explicit negative exclusion ("Do NOT use for brand voice, tone, identity or saved facts"), and names the correct alternative (get_brand_context). That is the full when/when-not/alternative triple.

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 destructiveHint=true and idempotentHint=true, but the description adds concrete substance: replacement semantics per field, the partial-update guarantee ('Only the fields you pass change'), and an explicit confirm-with-user-before-writing caution. It stops short of covering failure modes or what the response returns, which keeps it at 4 rather than 5.

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

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

Three sentences, all front-loaded: trigger first, then the destructive-replacement warning, then the partial-update rule, then the sibling redirect. No sentence is filler and the ordering matches the agent's decision sequence.

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, zero-required mutation tool with annotations but no output schema, the description covers purpose, triggers, replacement behavior, and the sibling alternative. It leaves open what happens when the named brand doesn't exist and what the response looks like, which is a minor gap given the schema carries the per-field and brand-selection guidance.

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 every parameter already has a documented meaning, so the baseline is 3. The description echoes the field list and clarifies that unspecified fields are untouched, which is mildly useful but adds no format or validation guidance beyond the schema.

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

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

States a specific verb set (rename, set, replace) against a named resource (brand) and enumerates the exact identity fields in scope. The agent can distinguish it from get_brand, create_brand, and remember_brand_fact without opening any schema.

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

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

Opens with an explicit trigger ('when the user asks to rename a brand or to set or replace its core identity') and names the alternative for the adjacent case: 'For adding a short fact without replacing anything, use remember_brand_fact instead.' Both when-to-use and when-to-use-something-else are stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuinely non-schema prerequisite — the user must have confirmed the change — which is the kind of behavioral context annotations cannot express. It stops short of saying that supplied fields overwrite existing values and that omitted fields are left untouched, which for a destructive update would be useful.

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, the exclusion and alternative both front-loaded relative to any ambiguity. Every clause carries actionable information; nothing is padding.

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 mutation tool with rich annotations and a fully documented schema, the remaining gap is small. The description covers identity, prerequisites, and alternatives; it omits only overwrite semantics and multi-brand targeting, the latter of which the brand parameter already documents.

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%, with each of the six parameters explaining defaults, limits, and enum-like category values (including fallback behavior). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('change a Prompt or Skill they already saved') and enumerates the mutable fields (name, description, text). It is immediately distinguishable from save_prompt and save_skill, which it names explicitly.

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

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

Gives both the when ('user asks to change something already saved', 'after they have confirmed') and the when-not ('Do not use it to save something new'), and routes to the correct alternatives by name. No inference required.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered; the description adds the actual diagnostic surface (size, fact count, session status, last read). It does not discuss historical range, rate limits, or behavior when no context has ever been saved, which is the main remaining gap.

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

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

Two sentences plus a short exclusion clause, with the trigger condition front-loaded before the do-not guidance. Every clause earns its place and nothing is repeated from the schema or annotations.

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

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

There is no output schema, so the description must carry the return payload, and it does: context size, number of saved facts, session status, and last read time. Combined with the zero-parameter schema and read-only annotations, an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, which is the correct baseline of 4; the description implicitly confirms it is a pure diagnostic call requiring no inputs. There is nothing further to document.

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 diagnostic verb (verify delivery) plus exactly what is reported: context size, saved fact count, session status, and last-fetch time. It explicitly distinguishes itself from the sibling get_brand_context, which reads the context itself, so an agent can separate the two 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?

Names concrete trigger conditions (user asks whether Nokbase is working, whether saved context reaches their AI tools, or when it was last read) and adds an explicit when-not clause routing to get_brand_context. Nothing 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.