Gnosari MCP

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond annotations: it verifies against the account's default domain (joina.chat) and, when taken, surfaces a suggested available alternative in the response. It doesn't discuss rate limits or error modes, but this goes well beyond what annotations provide.

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 core purpose, then scope (default domain), then the value-add on taken URIs. No filler, no repetition of the name or title.

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 tool is simple (1 param, read-only) and has an output schema, so return values need not be explained. Annotations cover safety and idempotency, the schema covers the parameter, and the description adds the domain scope and the alternative-suggestion behavior, which is exactly the context an agent needs to call it and interpret the result.

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

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

Schema coverage is 100% and the single parameter (uri) is documented in the schema with an example ('my-agent'). The description confirms the parameter is a URI slug but adds no format, length, character, or case-sensitivity details beyond what the schema provides. Baseline 3 is appropriate when the schema carries the 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?

States a specific verb ('Check') and resource ('URI availability'), with the concrete purpose ('for publishing an agent') and scope ('account's default domain joina.chat'). No sibling tool does URI availability checking, so it is clearly distinguishable from gnosari_create, gnosari_update, etc.

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 when to use it: before publishing an agent, to avoid a taken URI slug. It does not name an alternative tool or state exclusions, but the workflow context (pre-publish validation) is clear. No explicit 'when not to use' is given, which is the only gap.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds meaningful behavioral context beyond that: it describes what action='get' returns (per-attribute provenance with verbatim quotes and session_excerpt), what 'stats' returns (counts by template, status breakdown, trends), and the pagination model. It doesn't discuss auth or rate limits, which keeps it below 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 one-line purpose followed by per-action breakdowns and two tips. It is somewhat long and the Args section partially restates the schema descriptions, but each section is scannable and earns its place. Minor redundancy with the schema keeps it from a 5.

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

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

For an 11-parameter, multi-action tool with an output schema available, the description covers action semantics, workflow, return contents per action, and an alternative bulk path. Nothing an agent needs to select the right action or interpret results is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds action-conditional semantics the schema does not (agent_id/entity_id roles per action, days meaning 'omit for all-time', and the action-conditional scope of template_name/status/search/skip/limit/include_facets). This exceeds what the structured fields convey.

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 (list/fetch/summarise) and resource (data agents collected from conversations), and breaks the tool into three clearly-scoped actions. It distinguishes itself from siblings like gnosari_collected_data_delete (which is destructive) and gnosari_manage_data_collection (which configures collection).

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

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

Explicitly routes between actions ('Use this after list to drill into a record'), gives a recommended workflow (stats -> list -> get), and names an alternative route (REST export endpoint) for bulk downloads when paging is unsuitable. This is unusually complete usage 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 destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: the dry-run confirmation flow, account-scoping where foreign ids are silently skipped, that 'deleted' counts only your rows, and that the action is irreversible. This is exactly the extra behavioral detail an agent needs before a destructive call.

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

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

Front-loads the destructive nature and then the mode-dependent behavior in short, scannable paragraphs. The trailing Args block duplicates the schema descriptions, adding minor redundancy, but overall it is tight and well ordered.

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

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

With an output schema present, return values need not be described; the description covers everything else an agent needs — irreversibility, the confirmed gate, and account-scoped id behavior. Nothing material is missing for a destructive 2-parameter tool.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds meaning beyond the schema: it explains that entity_ids outside your account are silently skipped and how that affects the deleted count. The Args section otherwise restates 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 and resource ('Permanently delete collected data records') with examples (leads, feedback), so the agent knows exactly what is affected. It does not explicitly distinguish itself from the generic gnosari_delete sibling, leaving some routing 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?

Clearly explains the two operating modes: confirmed=False returns a confirmation summary with no deletion, confirmed=True performs the deletion. This tells the agent when to dry-run vs commit, though it never names an alternative tool for the read/list case (e.g. gnosari_collected_data).

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

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

Beyond the annotations, the description discloses substantial behavioral traits: all inputs are validated before any write, every error is reported at once, nothing is created on failure, and all components commit atomically. It also documents the ValueError condition when publish=True and the URI is already taken, including that the message suggests an alternative.

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

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

The description is front-loaded with the core action, then follows with requirements and behavioral guarantees in a logical order. It is efficient and avoids repetition, though the Raises section is slightly docstring-like and could be trimmed.

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

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

For a complex 12-parameter creation tool with nested objects and an existing output schema, the description covers the essential required inputs, atomic commit behavior, and error reporting. It does not explain all parameter interactions (e.g., greeting overriding empty_state is left to the schema), but the key behavioral context is 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 the schema already documents each parameter thoroughly, including defaults, enums, and nested field definitions. The description reinforces the required nature of welcome screen and data_collection but adds no new semantics beyond what the schema provides.

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

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

The description opens with a specific verb and resource: 'Create a fully-configured, data-collecting AI agent in one call.' It distinguishes itself from partial-management siblings by emphasizing all-in-one creation ('not a bare shell'), but it does not explicitly name an alternative such as gnosari_update or the gnosari_manage_* tools.

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

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

It clearly states the context: use this to produce a live-ready intake agent, with welcome screen and data_collection template as required. It also notes when to set greeting (which suppresses the empty state) and when to use publish=True, but it does not describe when *not* to use this tool or point to specific 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 flag destructiveHint=true, but the description goes further by enumerating exactly what is destroyed (public link, collected data, configuration) and asserting irreversibility ('This cannot be undone'), which is precisely the extra context an agent needs before a destructive call.

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 effect, then the confirmation contract, then the consequence. No filler and no repetition of the tool title.

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

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

An output schema exists so return values need no explanation, and the description covers the mutation's scope, reversibility, and confirmation gating. Nothing an agent needs to call this safely 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 already explains both parameters including the default and meaning of confirmed. The description restates the confirmation semantics rather than adding syntax or edge-case detail, 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 ('Delete an agent') and immediately qualifies the scope ('and all its associated data'), which cleanly separates it from gnosari_update, gnosari_create, and gnosari_collected_data_delete.

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?

Describes the two-step confirmation flow clearly: default confirmed=False returns details and a warning, confirmed=True performs the deletion. It doesn't name alternative siblings or state when deletion is inappropriate, but the dry-run guidance is strong enough that an agent knows how to sequence calls.

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

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

Annotations already declare readOnly/ idempotent/ non-destructive/ closed-world, so the safety profile is covered. The description adds real value beyond them: only non-default settings are emitted, the snippet is minimal by design, and it enumerates the two failure modes (AgentNotFoundError for a missing or foreign agent, AgentValidationError for a missing public URI).

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

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

Front-loaded with the core action, then organized into snippet behavior and a Raises block. Every sentence carries information, though the prose is slightly more expansive than needed for a tool this simple.

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 7 params, one required, 100% schema coverage, rich annotations and an output schema, the description covers the remaining gaps well: the public-URI precondition, the output's minimality, and the error cases. A cross-reference to gnosari_check_uri is the only notable 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 description coverage is 100% with enums and defaults documented for all 7 parameters, so the schema carries the semantics. The description only adds the meta-rule that defaults are suppressed in the output, which is not per-parameter detail; 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+resource: 'Generate an HTML embed snippet for the Gnosari chat widget,' and the body clarifies it returns a ready-to-paste snippet. This is clearly distinguishable from setup siblings like gnosari_manage_appearance, which configures the widget rather than emitting embed code.

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 a concrete precondition ('the Gnosari must have a public URI before it can be embedded') and states where the output goes ('paste it right before the closing </body> tag of every page'). It does not, however, point at the obvious sibling gnosari_check_uri as the way to verify that precondition.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, non-destructive), the description discloses a non-obvious behavioral trait: structured records appear a couple of minutes after a conversation ends, so processing=True means 'still processing' and False means 'nothing was captured'. That latency/interpretation context is exactly what annotations cannot convey.

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

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

Front-loaded with the core definition, then a compact explanation of why it beats guessing from an empty list. The trailing 'Args:' line largely duplicates the schema text, which is minor waste, but the rest of the prose earns its place.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose, the timing caveat, result interpretation, and the one parameter. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the single optional agent_id parameter is already documented in the schema. The description only restates it as 'Optional narrowing to one agent', adding no format, ID type, or default nuance beyond the structured field. 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 check ('whether any conversation capture is still being extracted') with a clear resource and scope. It also implicitly separates itself from gnosari_collected_data by explaining that an empty collected-data list is ambiguous while this tool resolves it. An agent can pick between the two 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 concrete when-to-use context: consult it to answer 'has the data landed yet?' rather than inferring from an empty list, and states the two result interpretations (still processing vs. genuinely nothing captured). It does not name the sibling tool (gnosari_collected_data) explicitly, but the condition that selects it is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered structurally. The description adds real value beyond that by disclosing the response payload shape (identity, access settings, appearance, knowledge, traits, data collection) and the readiness block with percent/missing keys/next steps, which tells the agent what it can act on next.

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 core verb and resource, followed by the payload contents and the one optional flag. The middle enumeration is long but earns its place by setting response expectations; 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?

An output schema exists, so the description need not explain returns, yet it helpfully previews the sections and the readiness block. For a two-parameter read tool with full annotation coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description's mention of include_instructions adds only the behavioral framing (full instructions text) already captured by the schema's 'Include full instructions text' description and default note. Baseline 3 is correct.

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 ('Get a complete overview of an agent's configuration') and enumerates exactly what the overview contains, so the agent knows this is the read-side counterpart to the many gnosari_manage_* mutators. It stops short of naming any sibling, so the differentiation is inferable rather than explicit.

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?

No explicit when-to-use/when-not, but 'Set include_instructions=True for the full instructions text' implies the cheaper default path versus the full-text path, and the tool's position among manage_* siblings is deducible from the read-only framing. Guidance is implied, not 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the return-content roster (status, name, version, API URL), but that duplicates the output schema and omits behavioral details such as whether it contacts the remote server or fails fast.

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 short sentences with the purpose front-loaded and no filler. Nothing could be removed without losing information.

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

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

With an output schema present, the return values need not be re-described, and annotations cover safety. For a zero-param, no-side-effect probe this is essentially complete, though it could note whether it performs a live network check versus a cached status.

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 are zero parameters, so the baseline is 4; the schema is empty and nothing needs explanation. The description correctly signals that the tool takes no input.

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 ('Health check') scoped to the Gnosari Manager MCP server, and names the returned fields. No sibling tool overlaps with a server-status probe, so it is trivially distinguishable.

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 phrase 'for monitoring Gnosari Manager MCP server status' gives clear context on when to call it (connectivity/liveness verification). It stops short of explicitly naming alternatives or when not to call it, but for a zero-argument probe no alternative is plausible.

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 cover safety (readOnlyHint=false, destructiveHint=false) and idempotency, but the description adds valuable behavioral detail: the publishing domain is resolved automatically, and specific ValueError conditions for invalid password/access-level combinations. It stops short of describing permissions or side effects on existing settings.

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

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

The description is front-loaded with the core purpose and then efficiently details the access levels and error cases. Every sentence is informative, though the raises section could be slightly tightened without losing meaning.

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 existence of an output schema and rich annotations, the description covers the essential behavior: access level semantics, automatic domain resolution, and validation errors. It does not mention the need to check URI uniqueness via a sibling tool, but the schema already enforces uniqueness, so this is a minor 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 schema already documents all four parameters, including enum meanings and the uniqueness/format of uri. The description reiterates most of this (e.g., joina.chat/{uri}, password gate) without adding significant new parameter semantics, so the baseline 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 (Configure) and resource (agent's access level and public URL) and explains the three access levels, making the tool's purpose clear. However, it does not explicitly differentiate itself from siblings like gnosari_update or gnosari_manage_link, which could be confused with access management.

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 access level descriptions imply when each mode is appropriate (PUBLIC for open links, PASSWORD_PROTECTED for a gate, PRIVATE for API/embed only), which provides implicit usage guidance. But there is no explicit statement of when to choose this tool over alternatives, no prerequisites, and no exclusions.

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

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

With annotations covering the safety profile, the description still adds substantial behavioral context: partial-update semantics ('only provided fields are changed'), the greeting-hides-welcome-screen overlay rule, the fact that suggested_prompts replaces all existing entries, theme-row reuse so repeated calls never duplicate themes, and the two failure modes with the note that ChatThemeConfigurationError names the offending key. Note a mild tension with idempotentHint=false, since a field-set operation that reuses the theme row in place reads as effectively idempotent, but the description itself is accurate and not misleading.

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, then bulleted by setting family, with the Raises block last — a logical order an agent can scan. It is somewhat verbose and restates a few things the schema already says (e.g. the greeting overlay), which keeps it out of the 5 range.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. For a 7-parameter mutation tool the description still supplies the missing pieces: partial-update behavior, the one-of-many requirement, replacement semantics, overlay precedence, and named error conditions.

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 and the schema already carries per-field detail (including the full style_preset enum rationale). The description still earns above baseline by grouping parameters into the CONTENT vs VISUAL mental model and by stating the partial-update contract, which the schema does not express.

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 concrete verb+resource ('Configure an agent's visual appearance and welcome experience') and then partitions the surface into CONTENT vs VISUAL identity, which cleanly separates it from adjacent siblings like gnosari_manage_instructions, gnosari_manage_traits, and gnosari_manage_data_collection. An agent can tell what this tool owns 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 real conditional guidance: 'pick ONE curated style_preset', 'greeting is an overlay: when set, the welcome screen ... is configured but hidden', and 'Only provided fields are changed; at least one is required'. What is missing is explicit routing against alternatives (e.g. when to use this vs gnosari_update), so it stops short of a 5.

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

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

Goes well beyond annotations: discloses preserve-on-omit on update, that removing never disables collection, that identity_field must name one of the template's fields, and that identity_field cannot be set alongside clear_fields. These are non-obvious behavioral rules an agent needs to call correctly.

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

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

Front-loads the action list then explains templates and their semantics. A few sentences are long, but each carries distinct information. Slightly dense but no clear 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 13 parameters, an output schema, and no nested objects, the description covers all the non-obvious behaviors (preserve-on-omit, assign vs remove, identity field handling) that the schema alone doesn't convey. Very 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?

Schema coverage is 100% so baseline is 3, but the description adds real meaning: the assign semantics of gnosari_id, the identity_field/clear_fields interaction rule, and the required-gnosari_id constraint for enable_attachments. This goes beyond restating 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 (create, list, get, update, delete, assign, remove) and resource (data collection templates), and explains what templates do. Sibling tools like gnosari_manage_knowledge and gnosari_manage_traits are in the same family but the description doesn't explicitly distinguish itself from them.

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 context: assign turns collection ON, remove never turns it off, and the enable state is owner-controlled. Explains the clear_fields vs value-param error condition. Does not name alternative tools explicitly, but the when-to-use semantics are well-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 only declare the safety flags (non-readonly, non-destructive, non-idempotent). The description adds real behavior beyond them: edits are all-or-nothing with failing-edit index reporting, anchors are byte-exact and must be unique, a confirm_replace guard fires past 2000 stored characters, and stale expected_version yields CONFLICT with nothing written. This is exactly the extra context annotations cannot carry.

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

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

The critical guidance (prefer edit, anchored spans) is front-loaded before the workflow and error notes. The Raises block earns its place by naming the failure codes an agent must handle, though the prose is dense enough that a tighter edit would help.

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 six params, a nested edit object, a rich output schema, and a stateful version contract, this is a complex tool — and the description covers the workflow, mutation semantics, conflict behavior, and error surface. Return values are left to the output schema, as appropriate.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema does most of the work. The description still adds value over it: the preference for edits over content, the prohibition on combining them, the 20-edit cap, and the version-threading contract. It stops short of explaining every field, hence not a 5.

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 upfront ("Update an agent's system instructions") and immediately distinguishes its modes (edit/replace/append/prepend) from the sibling gnosari_update used for clearing. An agent can tell exactly what this tool does and which sibling handles the adjacent case.

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 routing: prefer 'edit' for changes to existing text, 'replace' only for a whole new instruction set, append/prepend for additive changes, and gnosari_update(clear_fields) for clearing. It also spells out the create → get → manage flow with expected_version, 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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, but the description adds nothing beyond these – it doesn't say what delete destroys, whether removal from an agent is reversible, or that assign/remove mutate which agents can use a source. For a multi-action tool with a destructive verb (delete) present, the description's silence is a notable 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 short sentences, front-loaded with the action-set and resource. No filler. The second sentence clarifies the resource without 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?

Given 10 parameters, an output schema, and rich annotations, the description is adequate but thin. It omits when-to-use, the semantics of assign/remove versus create+assign, and any mutation caveats – leaving the agent to infer behavior from the schema alone.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters thoroughly, including the nuanced type/single_page interaction. The description adds no parameter-level detail beyond the action list, 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?

The description names a specific resource (knowledge sources) and enumerates all seven actions (create, list, get, update, delete, assign, remove) clearly. This distinguishes it from sibling managers like gnosari_manage_instructions or gnosari_manage_traits. It doesn't differentiate its scope from generic CRUD siblings, but the resource is well-defined.

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 lists action verbs but provides no guidance on when to use this tool versus alternatives, no prerequisites, and no context about the tools that consume knowledge sources. The generic 'Manage Knowledge' scope overlaps with other sibling tools, yet nothing routes the agent between them.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds real behavioral context beyond them: expiry semantics ('visitors then see 'link expired''), slug auto-generation for unguessable tokens, and per-link inheritance of greetings/themes. It does not describe the delete action's consequences or list pagination behavior, so not 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 core purpose, then usage rationale, then return values, with zero filler sentences. The return-value paragraph slightly duplicates what the output schema already carries, which is the only wasted space.

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 14-parameter multi-action tool, the description supplies the mental model an agent needs (link = URL + QR + presentation mode with per-link overrides) and defers per-parameter detail to a fully-covered schema and a return-value output schema. Deletion consequences and pagination are the only gaps, and those are minor.

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 each of the 14 parameters is already documented in the schema, including action-to-required-parameter mapping and enum meaning. The description adds only the conceptual model (a link carries greeting/topic/caption/theme/expiry) rather than new per-parameter syntax, 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 up front ('Create and manage shareable links for an agent') and immediately grounds it with the concrete artifact produced (unique URL, QR code, chat vs conversation rendering). An agent can distinguish this from sibling tools like gnosari_manage_appearance or gnosari_manage_access without inspecting 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?

Strong contextual guidance on why multiple links exist ('one link per channel (poster, email campaign, personal invitation) so each is tracked separately'), which tells the agent when to create several links rather than reuse one. It does not explicitly name alternatives or state prerequisites (e.g., that the target agent must already exist) or when to prefer get/list over create, so it falls short of a 5.

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

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

Annotations only assert the mutation profile (readOnlyHint=false, destructiveHint=false, non-idempotent), which is actually somewhat under-informative for a tool with delete/remove actions. The description compensates with concrete behavior: anchored edits are all-or-nothing and name the failing index, a stale expected_version triggers CONFLICT with nothing written, and the full-text path can demand confirm_replace past 2000 characters. It stops short of describing exactly what assign/remove or delete do to already-assigned agents.

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 verb list, then progressive disclosure through the preferred edit flow and the error taxonomy. The 'Raises:' block is useful but slightly verbose relative to the rest, and the multi-line prologue costs a little density.

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 13-parameter, 7-action tool with an output schema and rich annotations, the description covers the concurrency contract, the destructive-write guard, the error surface, and the recommended workflow. An agent could call this correctly on the first attempt without opening the schema for anything except the edit sub-fields, which the schema 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 coverage is already 100%, so the schema documents every parameter including the nested edit shape. The description still adds semantics the schema can't: the get→update→expected_version loop, the preference for instructions_edits over instructions, and the meaning of CONFLICT. It doesn't add much beyond the schema for the simpler action-scoped parameters, which caps it below 5.

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 an explicit enumeration of the CRUD-plus-assign verb set and the resource ('personality traits'), which is specific and distinguishable from siblings like gnosari_manage_instructions and gnosari_manage_knowledge. It also explains what a trait actually is ('shape how an agent communicates'), which no structured field conveys.

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 workflow (get → update with expected_version), names the preferred action for changing existing instructions (update with instructions_edits rather than whole instructions), and states the condition for the fallback ('Pass whole instructions only to write a completely new set'). That is when-to-use plus when-not, which is rare.

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 readOnlyHint=false, so the safety profile is covered; the description adds real value beyond them by disclosing that the signing secret is never returned, that event kinds come back with display names and descriptions, and that deliveries are paginated newest-first with outcome and failure reason. It stops short of stating that delete is irreversible or that activate/deactivate are the preferred path, which the schema covers.

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

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

Front-loads the purpose, then the action list, then two short clarifying notes; every sentence carries information. The event-kinds sentence is slightly tangential to selection but still useful, keeping it just under a perfect score.

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 multi-action tool with full schema coverage and an output schema, the description covers the action semantics, the secret-access limitation, and the diagnostic workflow without needing to restate return values. An agent has everything required to pick the right action and call it correctly.

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

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

Schema coverage is 100% (baseline 3), and the description still adds meaning: it explains what the deliveries history contains and how it should be used, and clarifies that event-kind values are human-readable topics rather than raw ids. It does not touch the confirmed/active parameters, but those are fully documented in the schema.

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

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

Opens with a specific verb+resource ("Manage outbound webhook destinations for the account") and then enumerates every action the single tool supports, so an agent knows exactly what surface it covers. It is clearly distinguishable from siblings like gnosari_manage_access, gnosari_manage_appearance, and gnosari_manage_data_collection.

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 action-level guidance (deliveries is for diagnosing failures; the secret cannot be read here and must be fetched from the dashboard URL) which steers behavior. It does not, however, state when to prefer this tool over sibling management tools, but those cover unrelated resources so no exclusion is strictly needed.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description adds real value beyond them: parallel fan-out across four entity types, grouped results, transparent SQL fallback, and the search_mode response field that reveals which backend ran. The one gap is that it does not quantify limits or latency, so a 5 is not warranted.

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 paragraphs, each earning its place: core purpose first, mode behavior second, backend/routing caveat third. No filler or redundancy with 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?

With an output schema present, return values need not be explained, and the description still flags the meaningful response field (search_mode). Combined with 100% schema coverage and annotations, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and every parameter is enum-annotated where relevant, so the schema carries the semantics. The description only restates the access_level scoping rule ('applies only to agents, silently ignored otherwise'), which the schema already says, adding little beyond the baseline.

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

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

Names a specific verb (Search) and resource (Gnosari entities), and clarifies scope: optional text query plus filters, returning results grouped by type or a single type. It does not explicitly contrast itself with read-only siblings like gnosari_get or gnosari_collected_data, so it stops short of the sibling-differentiation bar for a 5.

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

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

Clearly explains the two operating modes (entity='all' vs a specific entity) and when the OpenSearch/SQL fallback applies, giving the agent concrete context for choosing parameter values. It offers no explicit when-not or alternative-tool guidance against the 18 siblings, so it is clear context without exclusions.

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 and destructiveHint=false; the description adds real value beyond that by disclosing the partial-update semantics ('Only modifies provided fields'), the mutual-exclusion rule between clear_fields and value params, the empty-string prohibition, and the ValueError conditions. It stops short of stating reversibility or permission requirements, but the behavioral burden is largely carried.

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 primary purpose, then a scoping sentence, then focused paragraphs on the fiddly interactive_buttons and instructions behavior. Well-organized, though the interactive-buttons paragraph is dense and could be tightened.

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 9-param mutation tool that is part of a large sibling family, the description covers partial-update semantics, the exception routing for instructions, the clear_fields mechanism, and error conditions. An output schema exists, so return values need not be explained. Nothing material is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema cannot express: the clear_fields/param mutual-exclusion rule, that clear_fields reverts to canonical defaults vs NULL, and the prohibition on empty strings for interactive_buttons_behavior. These clarify non-obvious interaction between parameters, exceeding the schema's per-field text.

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

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

States a specific verb+resource ('Update an agent's identity and model settings') and explicitly carves out the sibling-managed domains (instructions, access, appearance, knowledge, traits, data collection). An agent can distinguish this from gnosari_manage_instructions or gnosari_manage_traits without opening a schema.

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

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

Explicitly names the alternative tools for the excluded domains ('use dedicated tools', 'managed by gnosari_manage_instructions'), states the precondition that at least one field must be provided, and documents the single exception where instructions clearing lives here. When-to-use and when-not-to-use are both fully covered.

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