ORYKSA AI Employees

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

Beyond the idempotentHint annotation, the description explicitly states that existing questions with matching text are updated, disclosing the upsert semantics. It also explains that the answer is the exact wording the agent should give, which is behaviorally important and not inferable from the schema or annotations alone.

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 deliver the core action and the update behavior with no filler or redundant restatement of the title. The most decision-relevant details—exact answer and same-text update—are 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?

The tool is simple: one required array parameter whose nested structure is fully visible in the schema, and annotations already communicate the non-readonly, idempotent, and non-destructive nature. The description adds the missing behavioral detail of how existing entries are handled, making the definition complete enough 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?

With 0% schema description coverage, the description adds key semantic value: 'answer' is the exact agent response, and 'question' text is the matching key for updates. It does not fully walk through the items array structure, but the schema already provides the required object shape, so the added meaning is sufficient.

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 the verb 'Adds' and names the resource 'frequently asked questions', then clarifies that the answer field holds the exact response the agent should give. It also reveals upsert behavior, making the tool's function unambiguous and distinct from the other oryksa 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?

The statement gives clear context for when to use the tool: whenever FAQ entries need to be created or updated for the agent. It does not explicitly name alternatives or exclusions, but the described behavior is specific enough that an agent would not confuse it with the sibling tools.

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 convey that this is a mutating but idempotent and non-destructive operation. The description adds one useful behavioral detail: greeting and suggestions are automatically generated when site content is stored, so manual settings may overlap with auto-generated ones. However, it does not explain what happens in that overlap (e.g., whether manual values override), nor mention any authentication, rate limits, or side effects. Overall, it adds some context beyond annotations but does not fully characterize behavior.

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 compact and front-loaded: the first sentence states the core function, the second adds a relevant behavioral note, and the third lists the language keys. Every sentence contributes. It is not overly verbose, though the auto-generation note could be seen as slightly tangential. Overall, efficient and well-structured.

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

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

For a tool with 6 parameters, nested objects, and no output schema, the description covers the key fields but leaves gaps: agent_name and gender are unexplained, and the exact object structure for greeting/suggestions is only implied via 'per language.' The language key list helps, but an agent might still need to infer the shape of the parameters. Given the moderate complexity, the description is adequate but not 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It adds valuable semantics: avatar_url must be a public https image URL and square, suggestions are limited to 4 per language, and greeting/suggestions/subtitle are keyed by language (pt, br, en, es). It covers most parameters implicitly, though agent_name and gender are not mentioned, and the structure of suggestion arrays is not fully spelled out. Still, it goes well beyond the schema.

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

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

The description explicitly states a specific verb ('Sets') and the resource (agent's chat appearance: photo, greeting, suggestions, subtitle). It distinguishes itself from siblings by focusing on chat customization rather than FAQ, links, domains, or site learning. The constraints (public https image URL, square, up to 4 suggestions per language) further clarify the scope.

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 purpose is clear enough that an agent can infer when to use this tool (to customize chat settings), but the description provides no explicit 'when to use vs. alternatives' guidance, no exclusions, and no mention of sibling tools. The auto-generation note hints at a scenario where manual setting may be unnecessary, but it does not directly guide tool selection.

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 mark the operation read-only, and the description adds meaningful behavior: it returns the embed code, describes the rendered widget behavior and look, and notes the single-placement requirement. There is no contradiction with the readOnlyHint.

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

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

Three dense sentences with the core return value and target frameworks up front; the widget-behavior details are relevant context rather than padding. Every sentence 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?

For a read-only, zero-required-parameter snippet tool, the description covers what is returned and where it should be used. It would be slightly stronger if it stated what the response looks like or the default framework/position, but nothing critical is missing for basic invocation.

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

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

Schema description coverage is only 33%, and the description does little to compensate: it repeats the framework enum but never explains position choices, language defaults, or what happens when parameters are omitted. An agent must infer the meaning of position and the optionality semantics from the bare 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 operation—returning the chat widget code—and specifies the resource (ORYKSA chat widget) plus the supported integration frameworks. It is clearly distinct from the sibling tools, which pertain to customization, FAQ, or setup rather than code retrieval.

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 explains the intended usage context: the snippet is placed once in the site's root layout. It does not explicitly list exclusions or name alternatives, but the context is clear enough to steer an agent toward this tool for installation code rather than for configuration.

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 description clearly states that the tool writes a business fact sheet and stores it as site content, which matches the mutating behavior implied by readOnlyHint=false. It also adds useful context about server-side crawling and the SPA limitation that can cause little text, going beyond the annotations without contradicting them.

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 compact and front-loaded: the main action, scope, and outcome appear in the first sentence, with a relevant caveat in the second. Every clause earns its place and nothing is redundant.

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 side-effecting, multi-step tool with no output schema, the description covers the main behavior and the key SPA caveat but omits what the agent can expect in return, whether existing site content is overwritten, and how failures are reported. It is adequate for a simple call but incomplete for confident operation.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'up to 30', which loosely relates to the max_pages bound, but it never names or explains the url parameter or how max_pages controls behavior. The agent gets no guidance beyond the schema's raw constraints.

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 ('crawls') with a clear resource ('a published website') and explains the outcome: writes a business fact sheet and stores it as agent site content. It is clear on its own, but it does not distinguish itself from the sibling tool oryksa_learn_site, which may overlap in purpose.

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

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

There is no guidance on when to use this tool versus alternatives such as oryksa_learn_site, oryksa_links, or oryksa_set_allowed_domains. The SPA caveat is a limitation, not a usage condition, and no exclusion or preferred-context criteria are provided.

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 description adds useful behavioral context beyond the annotations: it explicitly states that the tool 'Replaces the previously stored site content' and notes the fallback behavior that ORYKSA writes a business_summary if omitted. The annotations already signal idempotent and non-destructive behavior, and the description's replace semantics do not contradict them.

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 two tight sentences with no filler. It front-loads the core purpose, then adds the key replace behavior and summary detail. Every sentence 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?

For a storage-style tool with no output schema, the description plus input schema is sufficient for correct invocation: what to pass, how contents are structured, the replace semantics, and the optional summary fallback. The only real gap is sibling differentiation, which is already captured under usage guidelines.

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?

With schema description coverage at 67%, the description compensates by clarifying what 'content' means ('visible text of the page (no code, no markup)') and by describing the business_summary fact sheet categories. It also adds the fallback behavior for an omitted summary. It does not add much about site_url, but the schema already describes that parameter.

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 ('Stores') and identifies the resource ('website content' and optional 'business_summary') with concrete detail: visible customer-facing text, title, url, content. It is clear what the tool does, but it does not explicitly differentiate itself from the sibling oryksa_learn_from_url, which is a closely related alternative.

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

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

There is no explicit guidance about when to use this tool versus alternatives such as oryksa_learn_from_url or oryksa_add_faq. The description implies a purpose ('the AI agent uses to answer customers') but gives no conditions, exclusions, or routing hints. An agent must infer when to choose this over a sibling.

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, and the description adds value by listing the link categories and providing a domain-specific caveat: 'Channels that need a phone (WhatsApp QR) are always connected by a person in the dashboard.' This clarifies that the tool only returns links and that actual WhatsApp connection requires human action, going beyond the structured annotations.

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

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

The description is two sentences, front-loading the core content (what links are provided) and following with an important caveat. There is no filler or redundancy; every word contributes to the tool's understanding.

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 links tool, the description covers the scope of links and a notable behavioral nuance. It does not specify the exact output format (e.g., URL array vs. object), but given the simplicity, this is a minor gap that does not impede 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 input schema has zero parameters, so there is nothing for the description to clarify. Per the baseline rule for zero-parameter tools, a score of 4 is appropriate since no compensation is 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?

The description clearly communicates that the tool provides 'Links for the site owner' and enumerates the specific destinations (dashboard, conversations, connect WhatsApp or Telegram, upgrade the plan). This distinguishes it from the action-oriented sibling tools like oryksa_add_faq and oryksa_customize_chat. However, it lacks an explicit verb like 'get' or 'list', making the action slightly implicit though still unambiguous.

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

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

The description implies usage when the agent needs dashboard-related links for the site owner, but it does not explicitly state conditions or name alternatives. Given that all siblings are actions, an agent can infer this is the correct link/resource tool, but the description provides no direct guidance on when to use it versus others.

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, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate those. The description adds valuable behavioral context: the effect is restricting widget token usage to specified domains, subdomains are included, and an empty list disables restriction (allowing any site). This goes beyond the annotations by explaining the security implication and the localhost development use case. It doesn't mention rate limits or auth, but for this simple configuration tool, the added context is sufficient.

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 three sentences, each earning its place: the first states the core function and security rationale, the second gives the usage pattern with an example, and the third covers the empty-list edge case. It is front-loaded with the primary purpose and uses compact, clear language without redundancy.

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

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

For a single-parameter configuration tool with no output schema, the description is nearly complete. It covers what the tool does, how to use it, the parameter format, and the important edge case. The only minor omission is not describing the return value or success/failure behavior, but since there is no output schema and the tool is a simple setter, this is a small gap. The idempotentHint annotation also covers the repeatability aspect.

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 0%, so the description carries the full burden of explaining the 'domains' parameter. It does this well: it explains the parameter is an array of domain strings, provides a concrete example (['example.com', 'example.vercel.app']), clarifies subdomains are included, and explains the empty-list behavior. The only minor gap is not specifying the exact string format (e.g., no protocol, no wildcard support), but the example makes this reasonably clear.

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

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

The description clearly states the tool's purpose: restricting the chat widget to the site's domains, including subdomains, to prevent token misuse on other sites. It uses a specific verb ('Restricts') and resource ('chat widget'), and the domain restriction purpose is unambiguous. It distinguishes itself from siblings by focusing on domain allowlisting, which is unique among the listed 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?

The description provides explicit usage guidance: send production and staging domains, with an example format, and send an empty list to allow any site (useful for localhost development). This tells the agent exactly when and how to use the tool, including the edge case of empty list. It doesn't need to name alternatives because the domain restriction function is unique among siblings, but the guidance is still explicit and actionable.

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 mark the call as idempotent and non-destructive; the description adds the concrete partial-update behavior ('Fields that are not sent are left unchanged') and the upsert nature ('Creates or updates'). This gives an agent the key behavioral trait not visible in the schema, with no contradiction.

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

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

A single sentence front-loads the action, then lists the scope, then closes with the most important update semantic. Every clause earns its place and there is no redundant or promotional wording.

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 setup tool with no required fields, the description plus schema covers the full property surface and the partial-update behavior, and annotations cover the side-effect profile. The main gap is that no return/response behavior is described, and there is no output schema to fill that in.

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?

With 62% schema description coverage, the schema carries most parameter meaning. The description lists many parameters but adds little beyond naming them; undocumented properties like country, business_name, services, and message_style are not clarified, though they are mostly self-explanatory or enum-driven.

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-resource pair ('Creates or updates the AI support agent of the business') and enumerates the configurable fields, making the tool's purpose unmistakable. It also differentiates from sibling tools by scoping to business-agent configuration rather than FAQ, chat customization, or site learning.

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 create/update framing and 'Fields that are not sent are left unchanged' imply this is the tool for initial setup and subsequent edits, which is useful usage context. However, it never explicitly states when to prefer this tool over siblings or what circumstances would make it inappropriate.

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, so the description doesn't need to restate that. The description adds useful context about what specific status information is returned (plan, interactions, widget, knowledge). However, it doesn't disclose whether this makes any network calls, whether the status could be stale, or what happens if the account is not connected. With annotations covering the safety profile, a 3 is appropriate.

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

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

A single, well-structured sentence that front-loads the main purpose ('Shows the connected ORYKSA account') and then lists the specific data points. No wasted words, no repetition of the 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?

For a read-only status tool with no parameters and no output schema, the description is quite complete. It tells the agent what information it will get. The only minor gap is not describing the format of the output (e.g., whether it's a summary or raw data), but with no output schema and a simple status tool, this is a 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?

The tool has 0 parameters, so the schema is trivially complete. The description adds value by explaining what the tool reports, which is the closest thing to parameter semantics for a parameterless tool. Baseline 4 for 0 params 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?

The description clearly states the tool's function: showing the connected ORYKSA account status. It enumerates specific data points (plan, interactions left, widget availability, agent knowledge) and the verb 'Shows' is specific. It distinguishes itself from sibling tools, which are all mutation/setup tools, by being a read-only status view.

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 this is the tool to use when you need account/agent status information, and the sibling list confirms it's the only read-only status tool among them. It doesn't explicitly state when not to use it or name alternatives, but the context makes the usage clear: use this to check plan, interactions, widget availability, and agent knowledge.

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

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

Adds value beyond the readOnlyHint annotation by disclosing that the call does not count as an interaction and uses the same engine as production channels. No side-effect or auth details are given, but the annotation already establishes non-mutating behavior.

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 two tight sentences with front-loaded action and resource. Every clause adds information: customer-style question, text answer, engine parity, and no interaction count.

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 2-parameter read-only test tool, the description covers purpose, output, engine, and lack of interaction count. However, the history parameter is not explained, and with no output schema the description is the only source for return expectations beyond the brief 'text answer' phrase, making it slightly incomplete.

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 description only implies that the required 'message' is the customer question and provides no explanation of the optional 'history' parameter, its role, or how it affects the response. With 0% schema description coverage, the description should compensate but leaves history to inference from the property name and role enum.

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?

Description uses a specific verb ('asks') and resource ('AI agent'), and clearly frames it as a customer-style test question. It also names the output ('text answer') and distinguishes itself from configuration-focused siblings like oryksa_add_faq and oryksa_setup_business.

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: use this tool when you want to ask a customer-style question against the same engine used by WhatsApp and the website chat. It does not explicitly name alternatives or exclusions, but the test-vs-configuration distinction is evident from sibling names.

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