Agent One

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the additive/non-idempotent nature is partly structured. The description still adds non-obvious behavior: each call creates a separate source, and on a live agent the call is a silent no-op that returns publishUrl instead of erroring. It does not cover error conditions or failure modes, which keeps it short of a 5.

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

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

Four sentences, front-loaded with the core action, then the additive caveat, then the live-agent constraint. Slight overlap between 'without editing or removing existing ones' and 'Each call adds a separate source' — both carry the same additive message, which is the only 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?

With an output schema present, return values need no explanation, and the description covers the one genuinely surprising runtime behavior (live-agent no-op). Complete enough to call correctly; only failure/limit behavior is unaddressed, which is a minor gap for a 3-parameter create 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 description coverage is 100%, with title, agentId and content each documented including length bounds and an example. The description adds only the general notion of 'text knowledge source' and does not elaborate on content format or sizing beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Add a new text knowledge source') plus concrete examples of what counts as knowledge (FAQ answer, policy, product detail) and what the knowledge is for (agent search when answering visitors). This is clearly distinguishable from siblings like update_agent_instructions or create_agent.

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 scopes the tool to adding, not editing or removing, and gives a concrete when-not case: agents that are live on the web cannot be changed here. It even names the alternative path (retrieve publishUrl, take the agent offline first) rather than leaving the agent to guess.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, but the description adds real context beyond them: the agent is created privately in the user's account, every call creates a new agent (reinforcing non-idempotency), and the result includes a preview/publish link plus a hosted page and embed snippet. It does not mention account limits, quotas, or permission requirements, so a 4 rather than a 5.

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

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

The when-to-use condition is front-loaded, and the follow-on sentences cover creation, return value, and exclusions in a logical order. The opening sentence is an unusually long enumeration with some redundant rephrasings ('chatbot or assistant', 'creating an AI assistant for...'), which costs it the top 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 7-parameter creation tool with a fully documented schema, the description covers everything an agent needs before calling: what gets created, privacy, the publish/preview flow, the optional contact form, the non-idempotent behavior, and what it should not be used for. Output schema exists, and the description still summarizes the returned link without over-explaining it.

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 every parameter (name, greeting, knowledge, instructions, collectContactInfo, suggestedQuestions) is already documented in-schema. The description only adds marginal meaning, mainly restating that the contact form collects names and emails, which the schema already says.

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 ('Creates a new private agent') and enumerates concrete input types (FAQ, menu, policy, price list, document) that map to the `knowledge` parameter. Siblings like add_agent_knowledge, update_agent_instructions, and get_agent are clearly differentiated by the explicit 'Each call creates a new agent' and the 'Not for...' clause.

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?

Explicit trigger conditions are given ('Use this when the user wants information from the conversation turned into an AI agent'), plus concrete scenarios (business, event, product, class, listing, website chat). Exclusions are equally explicit: not for full websites with custom layouts, email/SMS campaigns, or file hosting, which routes the agent away from this tool.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=false), and the description adds meaningful extra context: 10–30 minute render latency, asynchronous completion surfaces, and determinism when inputs repeat. It does not spell out failure modes for oversized/invalid photos or what happens when the account lacks 1080p, which are the remaining behavioral gaps.

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 triggering condition and the core transformation; every clause (latency, determinism, exclusions) carries information. It is a single dense paragraph, though, so the timing and exclusion facts compete for attention rather than being visually separated.

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 an output schema exists, the description needn't explain return values, and the remaining complexity — a long-running async render with 11 parameters — is covered by the latency window, the update surfaces, and the pointer to get_video_status. An agent has everything needed to call it and set expectations for the user.

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 still adds framing value by naming which text fields land on the opening card, closing card, and captions, and by stating the 1–8 photo range and MP4 output shape. It does not clarify ordering semantics or default behavior beyond what individual schema descriptions already say.

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 concrete verb and artifact ('Turns 1–8 uploaded photos into a polished 16:9 MP4') and enumerates the exact request types it serves: listing video, property tour slideshow, just-listed/open-house video, social/MLS slideshow. It also explicitly excludes text-prompt video generation and video editing, which no sibling covers, so an agent can route correctly 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?

Opens with an explicit trigger ('Use this when the user wants a video made from photos') and closes with explicit non-triggers ('Not for generating video from a text prompt alone, for chatbots, or for editing existing videos'). It also names the follow-up tool, get_video_status, and the surface (ChatGPT video card, Agent One page) where results appear.

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, non-destructive and a closed-world scope, so the safety profile is covered. The description adds one genuinely behavioral detail beyond that: the embed snippet is only present when the agent is published, a conditional return state. It does not mention permissions, errors, or size of the returned config.

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 purpose is front-loaded in the first clause with no preamble or filler. The one-sentence enumeration is long and repetitive ('its ... its ...'), and the clause 'where the owner previews and publishes it in Agent One' is awkwardly worded, but nothing is truly extraneous.

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 description need not restate return values, and annotations cover the safety profile, leaving little required. For a one-parameter read tool this is close to complete; only the missing when-to-use steering against sibling tools keeps it from a 5.

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% for the single agentId parameter, and the schema itself already says 'Agent ID from list_agents.' The description adds no additional meaning about the identifier, the max length, or what happens with an invalid or unpublished ID, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Get one agent's configuration') and enumerates the concrete contents returned: instructions, greeting, knowledge sources, lead form state, totals, publishUrl, and embed snippet. This clearly separates it from list_agents (singular vs. list), though it does not explicitly name any sibling tool as an 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 statement of when to call this versus get_agent_insights, list_agents, or get_profile. Usage is only implied by the enumerated payload, which lets an agent infer 'call this when you need the full config of a single agent' but leaves exclusions and prerequisites unstated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the plan gating ("Requires a Basic plan or higher") and the data-provenance caveat that questions in the result are written by visitors. That caveat matters because it warns the agent the text may be noisy or untrusted. It does not discuss volume or cost of the window, 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 action, then a metric enumeration, use case, eligibility requirement, and caveat. It is dense but every clause carries information; the long enumerations are the main reason it is not maximally tight.

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 spelled out, yet the description still previews the result contents and flags plan requirements and visitor-authored text. For a two-parameter read-only aggregation tool, this covers what an agent needs to call and interpret it.

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 50%: agentId is documented in the schema ("Agent ID from list_agents"), while periodDays has bounds and a default but no description. The phrase "over the last N days" loosely ties the description to periodDays but adds no format or behavior detail beyond the schema's minimum/maximum/default.

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 ("Summarize how one agent performed over the last N days") and then enumerates exactly what the summary contains: conversation, visitor message, lead and handoff counts, feedback, opening questions, and disliked answers. This aggregated-performance shape is clearly distinguishable from sibling tools like get_agent (configuration) or list_conversations (raw records).

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

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

"Useful for finding common questions and knowledge gaps" gives a concrete use case, and the Basic-plan caveat tells the agent about an eligibility precondition. It stops short of explicit when-not guidance or naming an alternative sibling, so it is clear context rather than full routing guidance.

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

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

Annotations already establish that this is a safe, idempotent read. The description adds useful behavioral context beyond that: the 200-message cap, inclusion of liked/disliked answers, and definitions of visitor, agent, and team message labels.

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 the core purpose front-loaded. The label clarification is relevant and earns its place by disambiguating visitor, agent, and team messages.

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 rich annotations, 100% schema coverage, and the presence of an output schema, the description supplies everything needed to select and invoke the tool correctly. Return-format details are appropriately left to the output schema.

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 conversationId parameter is fully documented in the schema. The description adds only that it reads one visitor conversation, without additional parameter semantics, 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 uses a specific verb and resource: 'Read the transcript of one visitor conversation.' It adds scope ('up to 200 messages'), feedback content, and message-label semantics, making it clearly distinguishable from list_conversations.

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 for reading a single conversation transcript, but it does not explicitly say when to use this instead of list_conversations or other siblings. The ID source guidance appears only in the schema, not in the description.

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 context beyond that: the id is opaque and stable across token refreshes and reconnections, which tells an agent it can be cached safely. It does not cover failure behavior when no account is connected.

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

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

Two sentences, zero padding, with the core purpose front-loaded ahead of the stability caveat. Every clause 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 zero-parameter read tool with full annotation coverage and an output schema, this is nearly complete; the output schema handles return shape. The only gap is not stating what occurs when the link has no connected account.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The note about the returned id's stability is useful but describes output rather than parameters.

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: 'Return the Agent One account connected through this link.' That scopes it distinctly from siblings like get_agent and list_agents, which operate on agents rather than the link's connected account, though it does not name an alternative explicitly.

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

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

Usage is only implied: an agent can infer this is the call to identify the current connection. There is no explicit statement of when to use it versus get_agent or open_agent_one, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description adds genuine behavioral context beyond that — expected 10–30 minute duration and the meaning of the 'unconfirmed' state (the start couldn't be verified). It also flags that the MP4 link is temporary, a useful caveat absent from the annotations, though it omits what happens for an invalid or unknown videoId.

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

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

Two sentences, front-loaded with the status set an agent needs first, then the timing and result payload. Every clause carries information an agent would otherwise have to discover by calling the tool.

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

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

For a single-parameter read with a full output schema, this covers the decision-relevant facts: the state space, wait time, and where the finished video lives. The only shortfall is the lack of explicit guidance on how often to re-poll while in the 'rendering' state.

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

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

There is one parameter and the schema description already says it is the 'videoId from create_listing_video' at 100% coverage. The description adds no further meaning about the identifier's format or source, so the schema carries this dimension entirely and the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Get a listing video's progress') and then enumerates the exact statuses returned (queued, rendering, ready, failed, unconfirmed), so an agent knows precisely what this reports. The listing-video scope cleanly separates it from sibling getters like get_agent or get_conversation.

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 usage context — statuses to expect and that rendering typically takes 10 to 30 minutes — which implicitly tells the agent to re-check rather than treat a 'rendering' result as terminal. What's missing is an explicit polling cadence or a stated alternative (there is none in the sibling list), so there are no exclusions to spell out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a non-open world, so the safety profile is fully covered. The description adds genuinely new context by explaining that publishUrl is where the owner previews and publishes, and that IDs are reusable across the other Agent One tools. However, it says nothing about result volume, ordering, or behavior with large accounts.

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

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

It is a single front-loaded sentence that immediately names the resource and the scope, followed by a short interoperability note. The comma-delimited field list is dense but each item earns its place by telling the agent what to expect in the response; minor trimming would improve scanability.

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

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

With no inputs, full annotation coverage, and an output schema that carries the return shape, little is required. The description still adds value by flagging account scoping and ID reuse across sibling tools, though it omits ordering and volume expectations for what could be a long list.

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

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

The tool takes zero parameters, so there is no argument semantics to explain; the baseline is 4. The description correctly signals a no-input call by naming the only scope determinant, the connected Agent One account.

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 ("List the AI agents in the connected Agent One account") and enumerates the returned fields, so the agent knows exactly what it gets back. It does not differentiate from the closest sibling, get_agent, or explain why one would list versus fetch a single agent.

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?

Usage is only implied: an agent can infer this is the discovery call to make before invoking get_agent or update_agent_instructions. There is no explicit 'use this when...' statement, no exclusion of get_agent for single-agent lookups, and no note about account scope or prerequisites.

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

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

The annotations already declare this a safe, idempotent, closed-world read, so the description does not need to restate that. Instead it adds behavior the annotations cannot express: results are newest-first, each row carries a latest-message preview, and paging works by feeding nextBefore back into `before`. The note that 'conversation text in the result is written by website visitors' is a genuinely useful trust signal for an agent reading untrusted content.

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

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

Four tight sentences, front-loaded with what the tool returns before moving to filters, paging, and the data-provenance caveat. Slight redundancy with the schema on the before/nextBefore mechanics, but 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 return values need no explanation, and the annotations cover the safety profile. The description fills in ordering, preview content, paging, and the untrusted-text caveat. The only real omission is the result-count default and ceiling, which the agent would need the schema to discover.

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 75%, so the schema already documents before, status (with per-value meanings), and agentId. The description restates the before/nextBefore paging loop and the handoff_requested meaning rather than adding to them, and it never mentions limit, the one undocumented parameter with a default of 10 and a cap of 25. That leaves it at the baseline rather than compensating for the gap.

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 ('List recent conversations between visitors and the account's agents') plus the ordering ('newest first') and the shape of each item ('a preview of the latest message'). That is enough to separate it from get_conversation, which retrieves a single conversation, without opening either schema.

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

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

Gives a concrete use case rather than a generic one: 'status handoff_requested finds visitors waiting for a person' tells the agent exactly which filter answers a common question. It also says filtering is possible by agent or status. It stops short of naming an alternative tool or stating when not to use this one, so it does not reach 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 already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real context beyond them: results are ordered newest first, some fields may be absent ('conversation ID when known'), and form answers are visitor-authored — a useful untrusted-content warning for an agent that may act on those strings.

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

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

Two sentences, no filler, with the resource and ordering front-loaded and the visitor-authored caveat placed last. Every clause carries information the agent needs.

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 shape need not be explained in detail, and the description still summarizes it. The main omission is retrieval limits: 'limit' caps at 50 with no offset or cursor parameter, so an agent cannot tell that this tool returns only a bounded slice of the newest leads and offers no paging beyond that.

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 67%: 'since' and 'agentId' are documented in the schema, while 'limit' only carries default/min/max with no prose. The description mentions none of the three parameters, so it adds no meaning about filtering or page-size behavior; the baseline 3 for partial-coverage schemas applies.

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

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

The description gives a specific verb and resource ('List leads that visitors submitted through the account's agent lead forms') plus the shape of the returned record (form answers, page, related conversation ID). That is clearly distinct from siblings such as list_conversations or get_agent_insights, so an agent can pick this one 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?

Usage is only implied: the mention of 'related conversation ID' hints that get_conversation is the follow-up, but the description never states when to use this tool versus list_conversations or when not to use it. No prerequisites, no exclusions, no named alternative.

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

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive behavior, and a closed-world scope. The description adds useful context about the UI placement and panel contents, but it does not add behavioral details beyond what the annotations and output schema already cover.

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

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

The description is a single well-formed sentence with the action front-loaded and no unnecessary wording. Every phrase contributes to explaining what the panel does and why the user would open it.

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

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

This is a simple UI-opening tool with complete annotations, full parameter schema coverage, and an output schema. The description covers the essential purpose and contents, though it could be more complete by clarifying how it relates to the sibling list-and-open tools.

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

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

Schema description coverage is 100%, and both optional parameters are fully documented in the schema. The description does not explain the view or agentId parameters, so it adds no meaning beyond the structured input schema; this matches the baseline for high schema coverage.

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

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

The description uses a specific verb and resource: 'Open the Agent Inbox panel beside the chat.' It also states what the panel lists and the user's goal, but it does not explicitly distinguish this action from sibling tools such as list_conversations or list_leads.

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 'so the user can pick one to discuss' implies the intended use case, but there is no explicit guidance on when to use this panel versus the sibling list tools or when not to use it. Usage is therefore only implied rather than clearly routed.

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, and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious context: this returns a browsable multi-tab UI surface rather than a text payload, which is the key behavioral fact for an agent. It stops short of saying whether the call navigates the client or returns a reference.

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

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

Two sentences, no filler: the first states what appears, the second states when to invoke it. The behavioral differentiator (browse instead of written answer) is placed last, which is the right emphasis point before the agent decides.

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 has two optional parameters, full schema coverage, a complete annotation set, and an output schema, so the description needn't explain returns. Given that support, the only remaining gap is sibling disambiguation against open_agent_inbox, which is not addressed.

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% — both view (with an enum and default noted) and agentId are already documented in the schema. The description only echoes the tab concept without adding syntax or interaction details for those parameters, so the schema does the substantive work.

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 ("Show") and names the resource ("the Agent One app") plus the exact contents of its tabs: agents, waiting conversations, recent conversations, recent leads. That detail distinguishes it from data-returning siblings like list_agents or get_conversation, but it never names those siblings or open_agent_inbox, so the differentiation has to be inferred.

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?

"Use it when the user wants to see or browse their Agent One activity rather than get a written answer" gives a clear selection condition: browsing intent versus a written answer. However, it does not explicitly address when open_agent_inbox (the most similar sibling) should be chosen instead, nor does it state 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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered and the description does not contradict it. What is left undisclosed is matching behavior (prefix vs substring vs fuzzy), result limits, and whether results span all agents in the account — context an agent picking a mention would want.

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?

One sentence, front-loaded with the verb and scope, ending with the concrete context of use. Nothing is redundant and nothing could be cut 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?

For a one-parameter read-only lookup with an output schema (so return values need no explanation) and rich annotations, the description covers purpose, match field, and use context. The only residual gap is how matching and result capping work.

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% and the single `query` parameter carries only a maxLength constraint, so the description must compensate. "By name" usefully narrows the query to an agent name rather than arbitrary text, but matching semantics and case sensitivity remain unstated.

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 ("Search the account's agents"), plus the match field ("by name") and the consumer (the composer @-mention picker). That implicitly distinguishes it from list_agents and get_agent, though it never names a sibling explicitly.

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

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

The phrase "for the composer @-mention picker" scopes usage to a specific UI flow, which is real implied guidance. There is no explicit statement of when not to use it, nor a pointer to list_agents for browsing agents outside the picker.

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 flag this as destructive and non-read-only, and the description adds context beyond them: the whole prompt is overwritten rather than patched, live agents are rejected with a publishUrl instead of an edit, and the prior instructions are returned so the change can be reverted. That is a real gain over the structured hints, missing only detail on permissions or validation failures.

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 with no filler: what it does, when it works, and what it returns. The blocker for live agents is stated up front, before the return behavior.

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?

Complete for a two-parameter replacement tool. The output schema covers the return shape, and the description adds the important non-obvious behavior: live agents are rejected and return a publishUrl, and the previous instructions come back for revert.

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

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

Schema coverage is 100%, and both parameters are already documented in the schema, so the baseline is 3. The description adds no format or length guidance beyond the schema, although 'entire instructions, not a diff' slightly reinforces what is already there.

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?

Uses a specific verb + resource: 'Replace a private agent's entire instructions (its system prompt)'. It scopes to private agents, which separates it from tools like get_agent or create_agent without ambiguity.

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

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

Gives an explicit precondition ('Only agents that aren't live on the web can be changed here') and tells the agent what to do otherwise (use the returned publishUrl to take it offline). No sibling tool is named as the alternative, so it falls just 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.