ZeroRank - Track and improve your AI search visibility

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

Annotations already cover idempotency (idempotentHint=true) and non-destructiveness, but the description adds genuine behavior beyond them: mention history accrued while pending becomes visible immediately, and invalid/non-suggestion IDs are surfaced in `skipped` rather than failing. That is useful non-obvious context.

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 tight sentences, front-loaded with the core action and effect, then the immediate consequence, then the edge-case handling. No wasted 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?

No output schema exists, and the description partially covers the return by describing the `skipped` field, plus the state transition and history visibility. For a 2-param, fully-annotated mutation this is nearly complete, though it doesn't describe the overall success response shape.

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, but the description adds value by explaining what happens to ids that are missing or not suggestions (reported in `skipped`). This meaningfully informs how to interpret and supply the ids array beyond the schema's 'Suggested brand IDs to approve'.

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 (approve) and resource (suggested brands), plus the resulting state change ('become actively tracked competitors'). It even disambiguates the target by tying it to status 'suggested' in list_brands, so an agent can distinguish it from create_brand or update_brand.

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 clarifies the source of the IDs (status 'suggested' in list_brands), which implies when the tool applies. However, it never explicitly contrasts with the obvious sibling reject_suggested_brands or states when not to use it, leaving the selection condition implicit.

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 a non-readOnly, non-destructive, non-idempotent write; the description goes well beyond by disclosing the conflict outcome, the implicit side effect of approving/reviving a queued suggestion while preserving its mention history, and the fixed own-brand constraint. This is exactly the kind of hidden-behavior disclosure 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?

Three sentences, no filler, and the core action is front-loaded before the two edge-case behaviors. Each sentence carries distinct decision-relevant information.

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

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

For an 8-parameter creation tool with no output schema, the description covers the critical behavioral quirks and error mode. It omits what the call returns and any permission/rate-limit expectations, but the structured fields plus annotations mean little else is needed to invoke 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 description coverage is 100%, so every parameter (color, status, domains, useRegex, nameRegex, trackedNames, workspaceId) is already documented in the schema. The description adds no parameter-level syntax or defaults beyond the implicit note that new brands are competitors, which does not map to a specific field, 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 ('Add a competitor brand to track in AI answers') and immediately scopes it against siblings: it is not update_brand, and the CONFLICT clause clarifies it is a create-only path. An agent can distinguish it from approve_suggested_brands and delete_brand without opening any schema.

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

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

Gives clear conditional routing: if the name already sits in the suggestion queue it approves/revives that suggestion, and if an existing tracked brand shares the name it fails with CONFLICT. It does not explicitly tell the agent when to prefer approve_suggested_brands or update_brand, so it is strong context without full alternative/exclusion 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 this is a non-idempotent, non-read-only, open-world write, so the bar is lower; the description goes well beyond by disclosing the two distinct budget costs (monthly pitch allowance plus per-prompt answer runs per enabled model), async result delivery, the 30-day auto-archive, and the refresh path. These are material side effects an agent cannot infer from the 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?

Front-loaded with the create action, followed by cost warning and then the async workflow. It is dense but every sentence carries distinct, actionable information (cost, async, follow-up tools, archive, rerun) with no filler.

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

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

For a mutation tool with no output schema, the description supplies the full operational picture: budget consumption, async polling target, downstream read tools, archive lifetime, and refresh mechanism. Nothing an agent needs to invoke and follow through correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description reinforces that the domain drives prompt generation and frames optional parameters implicitly through the cost model (maxActivePrompts affects answer-budget charges). While it doesn't detail every optional field, the schema fully documents them and the description adds the domain-to-prompt semantic link.

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 ("Create a pitch workspace for prospecting") and immediately scopes what it does internally ("prompts are auto-generated from the prospect's domain and run ONCE"). This distinguishes it from siblings like create_prompt or create_brand without requiring the schema to be opened.

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 warning not to create speculatively ("a pitch is far from free — do not create them speculatively") plus the alternative flows named explicitly: poll get_pitch_status, then read via get_brand_rankings/list_chats/list_sources, and rerun_pitch to refresh. Both when-to-use and when-not-to-use are covered.

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

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

Goes well beyond the annotations by disclosing that prompts go ACTIVE immediately, that a first run is queued across every enabled model, that premium models cost up to 20x, that duplicate text+location pairs are silently skipped and surfaced in `errors`, and that the response includes org usage for pacing. These are consequential side effects an agent could not derive from readOnlyHint/openWorldHint/destructiveHint 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?

Four dense sentences, front-loaded with the core action, then side effects, then edge-case handling, then the return value. Every sentence carries distinct, non-redundant information; nothing is filler.

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

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

For a batch-mutating tool with billing impact and no output schema, the description covers the essential behaviors and even summarizes the response (`errors`, usage). It stops short of describing auth requirements or the full error/partial-failure semantics, which is a minor but real 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 already 100%, so the baseline is 3, and the description adds real value on top: the 1-25 batch bound and the duplicate text+location skip rule explain how the params combine in ways the schema does not. It does not add per-parameter detail beyond what the schema states, keeping it at a strong 4 rather than 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 gives a specific verb and resource ('Create 1-25 tracked prompts in a workspace') with an explicit batch bound. It also implicitly differentiates from the create_topic/create_tag siblings by stating those entities are auto-created by name when missing, so an agent can tell what this tool produces vs. the dedicated entity 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?

Usage context is implied rather than stated: the billing/answer-run warnings hint at when to be cautious, and the returned usage data hints at batching/sequencing. However, no explicit when-to-use, when-not, or named alternative (e.g., run_prompt, update_prompt) is given, leaving the agent to infer.

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 annotation set (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses concrete behavior: no duplicate is created and the existing tag is returned with alreadyExisted: true. It also flags the color constraint (named color, not hex; random if omitted). It stops short of describing permissions or the full return shape.

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 tight sentences, front-loaded with the core action, and every clause carries information: upsert behavior and the color constraint. No filler or repetition.

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

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

With a simple 3-parameter mutating tool, full schema coverage, and annotations covering the safety profile, the description supplies the one thing structured fields don't: the duplicate-handling return behavior (alreadyExisted). No output schema exists, and the description compensates by describing the notable return value.

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 baseline is 3, but the description earns a bump by emphasizing that the name drives the uniqueness/upsert behavior (name collisions return alreadyExisted) and that color must be a named value, not a hex code. These add meaning tied to the parameters beyond the schema 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?

The description gives a clear verb+resource ("Create a tag in a workspace") scoped to a workspace, which distinguishes it from read/delete siblings in spirit. It does not explicitly name the alternatives (update_tag, list_tags, delete_tag), so an agent must infer the boundary rather than being told outright.

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 implied: this is the tool for creating tags, and the upsert note tells the agent it's safe to call even if a tag may exist. However, there is no explicit guidance on when to prefer this over update_tag, nor when to look up an existing tag first via list_tags.

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 idempotentHint=true and destructiveHint=false, but the description adds concrete behavioral detail the annotations cannot: a duplicate name returns the existing topic with alreadyExisted: true rather than erroring or creating a copy. This is exactly the kind of nuance the agent needs and it is consistent with the idempotent annotation.

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 tight sentences with the core action front-loaded and the edge-case behavior immediately following. No filler or 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 no output schema, the description usefully covers the duplicate-return behavior that an agent could not otherwise anticipate. It is nearly complete for a simple two-parameter create tool, though it omits what a normal successful creation returns.

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 (name, workspaceId) are fully documented in the schema. The description adds no syntax, format, or constraint detail beyond what the schema already provides, 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 ("Create a topic in a workspace"), which cleanly identifies the operation. It does not explicitly differentiate itself from siblings like create_tag or create_brand, but the verb+resource pairing is 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 the create use case but offers no explicit when-to-use guidance, no prerequisites, and no routing to alternatives such as update_topic or list_topics. The duplicate-handling note implies when the call is safe but is not framed as 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 goes further by disclosing the consequence ('mention history is orphaned') and the non-obvious side effect that the discovery pipeline may re-suggest the brand later. It also states an authorization-style constraint (own brand cannot be deleted) that annotations do not 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?

Three tight sentences arranged in priority order: what it does, why to avoid it, who cannot use it, and the required flag. No filler, no restatement of the tool name.

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

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

No output schema exists, and the description covers permanence, orphaned data, re-detection risk, the safer alternative route, an eligibility restriction, and the required confirmation flag. Nothing an agent needs to invoke this destructively and correctly is missing.

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

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

Schema coverage is 100% and the schema already documents id, confirm, and workspaceId (including where to get workspace IDs), so the baseline is 3. The description adds real constraint semantics beyond the schema for the id parameter: the own brand cannot be deleted, which narrows valid values in a way the schema does not.

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 a competitor brand') with an explicit scope qualifier ('competitor') that separates it from update_brand and the other brand-management siblings. An agent can identify the operation without opening the schema.

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

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

Gives an explicit alternative and the condition selecting it ('prefer update_brand with status "hidden" ("Not tracking"), which keeps the row and blocks re-detection'), plus two hard preconditions: the own brand cannot be deleted, and confirm: true is required. This is textbook when/when-not 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, so the safety profile is known, yet the description still adds the irreversibility detail ('analytics are wiped and cannot be recovered') and the human-in-the-loop confirmation requirement. That is meaningful behavioral context beyond the structured fields.

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 destructive scope is front-loaded in caps, followed immediately by the safer alternative and the gating requirement.

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 3-parameter destructive mutation with no output schema, the description covers what is destroyed, that it is unrecoverable, the reversible alternative, and the confirmation gate. 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 coverage is 100%, so the baseline is 3, but the description adds real semantic weight for confirm — it must be true and only after informing the user — which the schema only states as 'Must be true'. The id/workspaceId parameters gain nothing extra beyond the schema.

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

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

States a specific verb (delete) and resource (prompt) plus the full blast radius ('all of its tracking history'). It also names the sibling it must not be confused with, update_prompt, so an agent can route correctly 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?

Explicit when-not: prefer update_prompt with status "paused" for reversible tracking stop. It also states a precondition for use ('confirm: true, to be set only after informing the user'), which is actionable sequencing guidance rather than vague context.

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, and the description usefully adds what is and is not destroyed: the tag assignment is removed, other tags on prompts remain, and analytics are unaffected. That scope clarification is real value beyond the annotations, though it stops short of stating auth/permission needs.

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

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

Three short sentences, front-loaded with the action, then the two scope caveats. No filler and nothing repeated from the name or schema.

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

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

Reasonably complete for a simple two-parameter delete with rich annotations and no output schema. However, for a destructive operation it omits recovery/reversibility expectations and any permission requirements, leaving a gap that the annotations only partially cover.

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% (both id and workspaceId are documented, including a pointer to list_workspaces), so the schema carries the burden. The description adds no parameter-level meaning, matching the baseline for full 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?

States a specific verb and resource ('Delete a tag') that is unambiguous and clearly distinguished from sibling deleters such as delete_brand, delete_prompt, and delete_topic. An agent can identify the operation 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 implied by the name and the scope clarification, but the description never states when to use this versus update_tag or list_tags, nor any prerequisite beyond workspace resolution. The agent must infer context from the sibling set.

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, so safety is covered. The description adds genuinely new context beyond them: the cascade behavior (AI-suggested and rejected prompts are deleted with it) and a named failure mode (TOPIC_HAS_PROMPTS) with a recovery step. Return values and idempotency confirmation are not addressed, keeping it just under the top mark.

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

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

Two sentences with a parenthetical, zero waste, and the core action is front-loaded ahead of the failure condition and cascade 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?

No output schema exists, so the description must carry behavioral burden, and it does: precondition, error code, and cascade destruction are all stated. It is largely complete; only explicit guidance on non-active prompts or confirmation behavior is absent.

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 (id, workspaceId) are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline 3 when the schema carries the load.

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

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

States a specific verb+resource ('Delete a topic') that cleanly distinguishes it from siblings like create_topic, update_topic, and list_topics. The purpose is unambiguous without opening the schema.

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

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

Gives a clear precondition and remediation path ('pause or re-assign them first') when TOPIC_HAS_PROMPTS is hit. It stops short of naming an explicit alternative sibling (e.g., update_topic or delete_prompt), so it's strong context rather than full when/when-not routing.

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

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

Annotations already declare idempotentHint=true, readOnlyHint=false and destructiveHint=false, so the description earns credit for adding auth requirements (owner/admin role), an entitlement gate (shareable-dashboards plan), and the concrete idempotency consequence ('re-enabling keeps the existing link'). It does not describe failure behavior when the plan gate is unmet or how a share is later revoked, keeping 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?

One sentence, front-loaded with the verb and resource, with the clarifying aside and the two constraints appended in priority order. No filler and nothing repeated that structured fields already carry.

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 mutation with no output schema, the description covers the essentials an agent needs: what changes, what is returned (the URL), the idempotent behavior, and the authorization/plan prerequisites. Nothing material is left for the agent to guess.

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

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

Schema description coverage is 100% and the schema itself even tells the caller to source workspaceId from list_workspaces, so the parameter is fully documented in structured data. The description only restates 'for a workspace' and adds no format, range, or lookup guidance beyond the schema — 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 (enable), a precise resource (the public/tokenized dashboard share for a workspace), and names the artifact produced (its URL). The parenthetical gloss 'the link agencies send prospects' removes any ambiguity about what a 'dashboard share' is, which matters because no sibling tool touches sharing.

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 clear preconditions for use — caller must be a workspace owner/admin and the plan must include shareable dashboards — so an agent knows when the call is even legal. It stops short of naming when not to use it or what alternative exists if the plan gate fails, so it is not a full 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on what fields are returned, whether a missing ID errors or returns empty, or any permission requirements.

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 front-loaded sentence with zero waste. It is arguably under-specified rather than over-long, but there is no filler to trim.

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 two-parameter read tool with full schema coverage and explicit annotations, the description is minimally viable. It omits the returned field set and any error behavior, which matters somewhat since no output schema exists.

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, including the useful hint that workspaceId comes from list_workspaces. The description's 'by ID' merely restates the schema and adds no new syntax or format 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 ('Get') and resource ('brand') scoped to a single record identified by ID, which distinguishes it from the list_brands sibling. It does not explicitly name the alternative tools, but the single-record scope is clear from the wording.

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 statement of when to use this over list_brands or get_brand_rankings, and no prerequisites such as needing an ID obtained from list_brands. The only routing hint is buried in the schema's workspaceId description, not in the tool description itself.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the metric dimensions of the ranking, which is useful domain context, but says nothing about ordering, ranking basis, tie-breaking, or return shape.

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 front-loaded sentence with the verb, resource and scope in the first clause and the metric list as a compact parenthetical. Nothing is padded.

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

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

No output schema exists, so the description should ideally convey what a ranking entry looks like (ordering, scoring scale, per-brand vs aggregate). The parenthetical hints at returned dimensions, which partially compensates, but ranking semantics remain unexplained.

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%: 'days' documents the default (7) and max (90), and 'workspaceId' points to list_workspaces. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (brand performance rankings) and enumerates the metric dimensions covered: mentions, sentiment, visibility, growth. That is enough to distinguish it from the sibling CRUD tools (create_brand, update_brand, list_brands), though it never names 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?

There is no when-to-use guidance, no stated prerequisites beyond the schema's required workspaceId, and no routing to related tools such as get_brand or list_brands. The agent must infer usage entirely from the name.

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 it as a safe read (readOnlyHint true, destructiveHint false, openWorldHint false), so the safety profile is covered. The description adds that the response is the complete, untruncated record including cited sources — meaningful return-shape context given there is no output schema. It omits any note on rate limits or error behavior for missing IDs.

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 tight sentences: the core capability first, the use case second, the ID source last. No filler and nothing buried.

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

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

For a simple two-parameter read-only fetch with no output schema, the description covers purpose, prerequisite lookup, and the shape of the returned payload. An agent has everything needed to select and invoke 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 description coverage is 100%, with both id and workspaceId already documented, including their sources (list_chats, list_workspaces). The description restates where to get the chat ID but adds no format or constraint detail 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 ('Get') and resource ('one AI chat execution') and enumerates the returned content (answer text, question, model, metadata, sources). The word 'FULL' and the pointer to list_chats clearly separate it from the sibling that only lists chats.

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 this to analyze what an AI model actually said' supplies the intent, and 'Get chat IDs from list_chats' routes the agent to the prerequisite sibling. It does not state when NOT to use it or other alternatives, but the context is unambiguous.

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

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

Annotations already declare this is a safe read (readOnlyHint true, destructiveHint false), and the description adds substantial context beyond that: answers arrive asynchronously with no retries, the polling cadence, the meaning of 'complete' vs 'partial', that 'partial' is permanent for the run, and that resultsReady is the go-signal. This is rich disclosure well above the annotation baseline.

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

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

Front-loaded with the purpose and efficient overall, but it is a dense run-on paragraph with stacked parentheticals that slightly impede scanning. Every clause does carry meaning, so waste is minimal.

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

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

With no output schema, the description carries the burden of explaining return signals and does so: it defines the 'complete'/'partial' states and flags resultsReady as the fetch go-signal. For a single-parameter async status tool this is complete enough to call 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% for the single workspaceId parameter, and the schema already explains where to obtain it via list_workspaces. The description adds no further parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific verb and resource — reading the readiness of a pitch workspace's latest run — which is clearly distinct from siblings like get_workspace, list_workspaces, and rerun_pitch. An agent can identify the tool's role 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?

Provides concrete operational guidance (poll every 30-60s) and routes the agent when the run is 'partial' by naming the alternative rerun_pitch. It stops short of stating when-not to use it versus other status/workspace tools, so it is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered, and the description adds no behavioral context on top of that. It says nothing about error behavior for a missing/foreign-workspace ID, permission requirements, or what the returned 'details' comprise.

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 nine-word sentence with the verb and resource front-loaded and zero filler. Nothing is padded or repeated from 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 simple two-parameter read tool with fully documented params and safety annotations, the essentials are present. The remaining gap is that no output schema exists, so the description could have said what 'details' are returned, which would help an agent decide between this and list_prompts.

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 workspaceId description even routes the caller to list_workspaces, so the schema carries the parameter burden. The description adds no syntax, format, or relational meaning beyond what the schema already provides, making the baseline 3 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 ('Get details') and resource ('a specific prompt by ID'), which is clear and unambiguous. However, it does not distinguish itself from siblings like list_prompts, get_brand, or get_workspace, leaving the agent to infer the boundary from the name alone.

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 when-to-use guidance and no mention of alternatives such as list_prompts (for enumeration) or run_prompt (for execution). The phrase 'by ID' weakly implies the caller must already hold an ID, but nothing states prerequisites or 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without the description. The description adds mild value by naming the fields returned (useful since there is no output schema), but discloses nothing about auth, errors, or lookup failure 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?

One tight sentence with the verb and resource front-loaded and returned fields parenthesized; nothing is wasted. It is perhaps slightly too terse to be fully explanatory, which keeps it off 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 a single-parameter read tool with annotations covering safety and a fully documented schema, the description is nearly sufficient: it names the resource and the returned fields, compensating for the absent output schema. It could still note the single-workspace scope versus list_workspaces, but no agent-blocking information is missing.

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

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

Schema description coverage is 100% for the single workspaceId parameter, so the schema carries the semantics, including how to obtain an ID. The description contributes no additional meaning about the parameter, which is the correct baseline of 3.

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

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

States a specific verb (Get) and resource (info for a workspace) and enumerates the returned fields (name, plan, subscription status), which makes the tool's scope concrete. It stops short of distinguishing itself from the sibling list_workspaces or get_workspace_models, relying on the schema's pointer instead.

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 gives no when-to-use or when-not-to-use guidance and never names an alternative. The only routing hint ('get the list from the list_workspaces tool') lives in the schema parameter description, not the tool description, so usage is left to inference.

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

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

Annotations already establish readOnly=true, destructive=false, openWorld=false, so the safety profile is covered. The description does add real semantic context not in the annotations — that runs only use enabled models — but it says nothing about ordering, pagination, or what the response looks like beyond the listed fields.

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, and the core action plus returned fields are front-loaded. The trailing sentence about enabled models is short and carries genuine information rather than restating the name.

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

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

With no output schema, the description must carry the return shape, and it does list the meaningful fields (weight, transport, enabled). It falls short only on ordering and size/volume expectations, which are minor for a single-workspace listing.

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?

Only one parameter and schema coverage is 100%, with the schema itself telling the agent to fetch the ID from list_workspaces. The phrase 'in this workspace' reinforces the scoping but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

It names a specific verb (List) and resource (trackable AI models) scoped to a workspace, and it enumerates the fields returned — per-run answer weight, transport, enabled status. That is enough to distinguish it from generic reads, though it never explicitly contrasts itself with the nearby set_workspace_models sibling.

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 when-to-use, when-not-to-use, or alternative guidance. The description never points to set_workspace_models as the mutation counterpart, even though it is the obvious adjacent tool. Usage is only inferable from the wording.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on pagination, result ordering, or whether archived brands are included.

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 short, front-loaded sentence with no filler. Nothing in it is redundant or wasted.

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 single-parameter read tool with full schema coverage and annotations carrying the safety profile, the description is adequate. Minor gaps around return contents/pagination keep it short of 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% and the single workspaceId parameter is fully documented in the schema (including a pointer to list_workspaces), so the baseline of 3 applies. The description adds no further parameter meaning.

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

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

States a specific verb ('List') and resource ('brands') with scope ('in a workspace'), which distinguishes it from singular siblings like get_brand and from list_workspaces. It does not explicitly name an alternative, but the purpose is 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?

There is no when-to-use guidance, no prerequisites, and no mention of when to prefer get_brand or another sibling. The usage is only implied by the verb 'List'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral fact beyond the structured data: results are lightweight summaries lacking full answer text and sources, which tells the agent not to expect complete content here.

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 with the core purpose front-loaded and the routing hint carried in a tight parenthetical. No filler, nothing to trim.

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

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

No output schema exists, but the description compensates by characterizing the return shape (lightweight summaries, no full text or sources). Combined with annotations covering safety and a fully documented schema, an agent has nearly everything needed; only ordering/pagination behavior is unspecified.

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 documents limit (default 20, max 50), promptId filtering, and workspaceId sourcing from list_workspaces. The description adds nothing about parameters, 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+resource ("List recent AI chat executions") and immediately qualifies the payload as lightweight summaries, which cleanly separates it from get_chat. An agent can distinguish this from the sibling get_chat 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?

Explicitly routes the agent to get_chat when full answer text and sources are needed, which is the key decision point against the most confusable sibling. It does not state exclusions (e.g. that this is a workspace-scoped listing, or anything about ordering), but the primary alternative is named with its selecting condition.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and closed-world scope, so the safety profile is covered. The description adds nothing beyond that — no ordering, pagination/cap behavior, or what happens when no results match — leaving the burden on the schema.

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

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

A single front-loaded sentence with zero filler words. It is efficient, though bordering on too terse to be 'appropriately sized' for a five-parameter 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?

With no output schema, the description should at least signal pagination or result shape, but it does not. Combined with complete schema coverage and safe read annotations, the omission is a gap rather than a failure.

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%, including the enum for status and the 'get from list_workspaces' hint for workspaceId, so the schema carries parameter meaning. The description's generic 'optional filters' adds no detail beyond it, making baseline 3 appropriate.

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

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

States a specific verb+resource ('List prompts') that is unambiguous about the operation and entity. It does not differentiate from siblings like get_prompt or create_prompts, but the verb 'list' plus the plural resource makes the read/enumerate intent clear.

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 'with optional filters' hints at narrowing results but never says when to use this tool instead of get_prompt (single retrieval) or how the filters combine. No exclusions, prerequisites, or alternative routing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds mild behavioral color by implying the result is a ranked, truncated ('top') list of domains rather than a complete one, but says nothing about authentication needs or how 'top' is ranked.

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 short, front-loaded sentence with zero filler. It is arguably too terse given the missing routing and scope detail, but there is no wasted language to penalize.

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 two-parameter read tool with full schema coverage and annotations that cover safety, the description is adequate but leaves two real gaps: no distinction from list_source_urls and no hint of what 'top' means or how results are ordered. With no output schema, ordering/ranking semantics would have been the highest-value addition.

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 limit (default 20, max 50) and workspaceId (with pointer to list_workspaces) are fully documented in the schema. The description adds no parameter detail beyond this, 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+resource ('List top source domains') and adds scope via 'cited by AI models', which is more informative than the name alone. However, it gives no differentiation from the sibling list_source_urls, which sounds closely related, so an agent cannot route between them from this text.

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?

Pure statement of function with no when-to-use guidance, no prerequisites, and no mention of when list_source_urls would be the better choice. The only usage-relevant fact (workspaceId is required) lives in the schema, not 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful domain of the data (AI-model citations) but says nothing about pagination, ordering, result caps, or auth/workspace scoping, leaving the behavioral picture thin.

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 compact sentence with the resource front-loaded and the optional filter trailing. Efficient, though it is so terse that it omits information rather than earning every clause.

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

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

For a simple read-only list tool this is minimally sufficient, and annotations cover the safety profile. However, with no output schema the description should indicate what a returned source URL entry contains and how results are ordered or paginated, and it says neither.

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 limit, domain, and workspaceId are all documented in the schema (including the max 50 cap and the list_workspaces pointer). The description only restates the optional domain filter, adding no syntax or format detail beyond the schema — baseline 3.

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

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

States a specific verb ("List") and a specific resource ("source URLs cited by AI models") with an explicit scope ("optionally filtered by domain"). It is clear on its own, but it never distinguishes itself from the near-identical sibling list_sources, so the agent must open both schemas to tell them apart.

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 "optionally filtered by domain" implies one usage context but states no when-to-use, when-not-to-use, or alternative. With a sibling named list_sources in the same workspace, the absence of routing guidance is a real 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the workspace-scoping frame but nothing about pagination, ordering, or result limits, so it is adequate rather than rich.

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 front-loaded sentence with no filler or redundant restatement of the tool name. 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?

For a simple, read-only, single-parameter list tool with full schema coverage and complete annotations, the description supplies what is needed to invoke it correctly. No output schema exists, but a list-returning tool is largely self-explanatory, leaving only a minor gap around result shape.

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 workspaceId parameter is documented there, including a pointer to list_workspaces. The description's 'in a workspace' corroborates but adds no format or sourcing detail 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 ('List all tags') plus the scope ('in a workspace'), which is enough to distinguish it from create_tag, update_tag, and delete_tag in the sibling set. It does not explicitly name an alternative, so it stops short of 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?

There is no statement of when to use this tool versus the sibling list_* tools or the tag mutation tools. The workspace scoping is implied by the name and schema but no usage context 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 readOnlyHint=true, destructiveHint=false, openWorldHint=false, covering the safety profile. The description adds nothing beyond that — no note on pagination, return shape, or workspace scoping 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?

One short, front-loaded sentence with zero filler; the action and scope come first.

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

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

For a trivial read-only list endpoint with a fully documented single parameter and safety annotations, the description is sufficient for correct invocation. Only minor niceties (return format, ordering) are absent.

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 workspaceId parameter already documents itself, including how to obtain it via list_workspaces. The description adds no additional parameter meaning, 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 (List) and resource (topics) scoped to a workspace, which is clear. It does not distinguish itself from siblings like create_topic/update_topic/delete_topic, but the action word makes the distinction self-evident.

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 guidance on when to use this versus alternatives such as get_workspace or the topic-mutation tools, and no prerequisites stated. Usage is only inferable from the verb.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that the call yields workspaceIds consumed by other tools, which is genuine context beyond the annotations, but it says nothing about return shape, count, or pagination.

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, zero waste, with the core purpose front-loaded before the usage hint. 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 parameterless list tool with no output schema, the description covers what it returns (workspaces) and how to use the result (the workspaceId). Without an output schema it could say more about the returned fields, but nothing critical to invoking it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description's reference to a 'returned workspaceId' slightly orients the agent to the output, but there are no input semantics to clarify.

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 clear verb+resource: 'List the workspaces you can access.' An agent can distinguish it from the singular get_workspace sibling by the 'List' verb, though it never names that sibling explicitly. The scope ('you can access') is a useful qualifier.

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 second sentence gives real workflow guidance: 'Use a returned workspaceId with the other tools.' That tells the agent why and where the output goes, but there is no explicit when-not or comparison to get_workspace (single-item lookup). Usage is implied rather than fully specified.

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 non-destructive, idempotent write behavior, but the description adds genuinely new context: rejection blocks re-detection and is reversible through update_brand. That reversal path is the key nuance an annotation cannot express. Return/rate-limit behavior is not covered, keeping it short of 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?

A single dense sentence with the state change front-loaded, followed by the recovery path and the error-reporting clause. No filler; every clause carries new 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 no output schema, the description compensates by documenting the `skipped` return field and the hidden-state side effect. Together with the fully-covered schema and annotations, an agent has everything needed to 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%, so the baseline is 3, but the description adds error semantics for `ids` — IDs that are missing or not suggestions land in `skipped`. That tells the agent partial failure is possible and how it surfaces, which the schema does not 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 specific verb+resource ("Reject suggested brands") and immediately distinguishes it from the sibling approve_suggested_brands by naming the resulting state. An agent can tell at a glance this is the negative counterpart to approval, not a delete operation.

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?

Explains the effect of using it (moves to "hidden"/"Not tracking"), implies the resumption path via update_brand, and warns that non-suggestion or missing IDs are skipped. It lacks an explicit statement of when NOT to reject (e.g., vs delete_brand), so it stops short of full routing guidance.

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

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

Annotations only declare the generic profile (non-read-only, non-idempotent, non-destructive); the description goes well beyond by disclosing the cost model — one monthly pitch allowance consumed, every prompt charged to the answer budget (one run per prompt per enabled model) — plus the 30-day expiry reset and archived-pitch revival. This is exactly the side-effect/cost context an agent needs before invoking.

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 front-loaded sentences, each clause carrying distinct information (cost, budget charge, expiry reset, revival, next step) with no filler or 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 non-idempotent mutation tool with no output schema, the description supplies the cost/budget consequences, the lifecycle effects, and the required polling follow-up. Nothing needed to call it safely and 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?

There is a single parameter with 100% schema description coverage, and the schema already tells the agent to source the ID from list_workspaces. The description adds no additional parameter semantics, so the baseline 3 for high coverage 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 (re-run) and resource (every prompt in a pitch workspace), with a clear scope qualifier ('every prompt') that separates it from the singular run_prompt sibling. An agent can identify the operation and its blast radius without opening the schema.

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

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

Gives clear context for use ('for fresh data') and routes the agent to the correct follow-up ('Poll get_pitch_status afterwards'), which is the necessary next step. It lacks an explicit when-not clause (e.g., prefer run_prompt for a single prompt), so it stops short of full routing guidance.

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

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

Goes well beyond the annotations: discloses budget consumption per model (premium up to 20x), monthly vs extra-answer reserves and their reset/expiry rules, the specific ANSWER_RUNS_TOTAL_LIMIT failure condition, the 5 calls/minute rate limit, and asynchronous delivery. Annotations only cover the safety profile, so this adds substantial operational context.

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 action, then layered with budget, failure, return-shape, async, and rate-limit facts. It is dense and every sentence carries information, though it runs long and could be tightened slightly.

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

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

With no output schema, the description still covers the return shape (answerRuns with used/limit/credits), the async delivery model and where to follow up, the failure mode, and the rate limit. It is complete for a 3-parameter mutation 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 the baseline is 3, but the description adds meaning beyond the schema: models may be a subset and defaults to every enabled model, and model choice directly affects budget consumption (premium up to 20x). This makes the cost of the models parameter tangible.

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: 'Queue an on-demand run of an ACTIVE prompt across the workspace's enabled AI models'. The scope (active prompts, enabled models, optional subset) is precise enough to distinguish it from siblings like rerun_pitch and create_prompts.

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?

Establishes the context clearly ('on-demand run of an ACTIVE prompt') and routes the agent to list_chats to retrieve async results. It does not explicitly contrast with alternatives such as get_pitch_status or rerun_pitch, so it stops short of full when/when-not 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 cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds substantial behavior beyond them: role requirements, partial-vs-complete map semantics via replace, the invariant that one available model must stay enabled, the restriction that available:false models can only be set false, and budget consumption per weight. This is rich, non-obvious operational context.

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 constraints in a dense but ordered paragraph; the crucial default-vs-replace distinction appears before the secondary constraints. No filler sentences, though it is longer than strictly necessary and could be segmented. Every clause carries operational weight.

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 mutating, nested-object tool with no output schema, the description covers role authorization, the partial/complete map, the enabling invariant, unavailable-model handling, and budget impact. 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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it states that unlisted models keep their current setting (the schema only spells out the replace:true case) and clarifies the replace semantics as a complete-map override. This disambiguates behavior an agent would otherwise have to infer.

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 pair (enable/disable) and resource (AI models for a workspace), which is unambiguous against siblings like get_workspace_models (read-only) or update_brand. An agent can identify the operation without opening the schema.

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

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

Gives prerequisites (owner or admin role), constraints (at least one available model must stay enabled), and routes to get_workspace_models for weights and availability. It lacks an explicit 'call get_workspace_models first' instruction, but the context is clear enough to select and use the tool correctly.

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 non-readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond them: the own-brand hiding restriction and the fact that suggested brands must be transitioned through approve/reject tools rather than this one.

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 tight sentences with no filler; the field list comes first and the routing constraints are front-loaded immediately after. Every clause carries information.

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

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

For a 9-parameter mutation tool with no output schema, the description supplies the mutable-field set and the key usage constraints, and annotations cover safety. Minor gaps remain (partial-update semantics, whether omitted fields are preserved), but nothing critical 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 78%, so the schema already documents most parameters (including null-clears semantics and the hex-color note). The description's field list roughly mirrors the schema without adding format or constraint detail, so baseline 3 is appropriate.

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

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

States a specific verb (Update) and resource (brand) and enumerates the mutable fields (name, aliases, domains, regex matching, status, color), letting an agent distinguish it from create_brand, delete_brand, and get_brand. It does not, however, explicitly name update-siblings it might be confused with, so it stops short of 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?

Gives concrete when/when-not guidance: 'The own brand cannot be hidden' and 'Suggested brands transition only via approve_suggested_brands / reject_suggested_brands', which routes the agent away from this tool for suggestion workflows. It covers exclusions well but does not describe general preconditions (e.g. needing the brand to exist or workspace scoping).

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 readOnly/idempotent/destructive hints, and the description adds the non-obvious traits they don't: billable-run side effect on reactivation, full-replacement semantics for tags (names auto-created, numbers must be existing IDs), and topicId:null detachment. Nothing here contradicts idempotentHint=true or destructiveHint=false.

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 editable-field list front-loaded, followed by the two highest-risk behaviors. No filler, no repetition of the tool name or boilerplate.

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 8-parameter mutation tool with no output schema, the description covers the important side effects and parameter edge cases well. The only gap is that it says nothing about what a successful update returns or whether all fields are applied atomically.

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

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

Schema description coverage is 100%, so every parameter is already documented, and most of the description's parameter detail (tag replacement, null detach, created-if-missing) restates it. The added value is limited to the cost note attached to status='active', so the baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Update a prompt') and enumerates the exact editable surface (text, status, location, tags, topic), which sharply separates it from the create/delete/run prompt siblings. An agent can tell immediately this is the partial-modification tool rather than a create or 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?

It gives a concrete usage condition with consequences: reactivating a non-active prompt consumes a slot and queues a billable run, so an agent knows when the call is expensive. It stops short of naming alternatives (e.g., run_prompt for on-demand runs) or stating when not to use 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 readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful failure mode not present in annotations: renaming to an existing tag's name fails with CONFLICT. It does not mention auth/permission requirements, 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?

Two short sentences, zero filler, and the primary action is front-loaded ahead of the error caveat. 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 simple update tool with full schema coverage, no output schema, and annotations covering idempotency and safety, the definition is nearly complete. The one residual gap is that it never states at least one of name/color should be supplied, nor any permission requirement.

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 id, name, color (with its full enum), and workspaceId are already documented in the schema. The description restates that name and color are the mutable fields but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb pair and resource scope: 'Rename a tag or change its color.' It bounds exactly which fields this mutation touches, which cleanly separates it from create_tag, delete_tag, list_tags, and the sibling update_* tools for other resources.

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 implied (use this to modify an existing tag rather than create or delete one), but no alternative is named and no precondition is stated, such as 'you must pass at least one of name/color' or 'use create_tag for new tags.' Adequate but with clear gaps.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, and the description still adds genuinely useful behavior: a duplicate-name rename fails with CONFLICT, which implies name uniqueness per workspace. It does not mention permission requirements or what happens on success, keeping it short of a 5.

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

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

Two short sentences with zero filler, and the core action is front-loaded before the failure-mode 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 three-parameter mutation with full schema coverage and no output schema, the description covers the action and the notable error case. The only gap is the absence of permission/precondition context, which is minor given the annotations already flag this as a non-destructive, idempotent write.

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 id, name, and workspaceId are already documented (including the pointer to list_workspaces). The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 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?

"Rename a topic" gives a specific verb and resource, and it accurately scopes the tool to the only mutable field (name) rather than the broader name update_topic. It does not explicitly contrast itself with sibling update_* tools, but the resource is unambiguous enough that an agent can distinguish it.

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 statement of when to reach for this tool versus list_topics, create_topic, or delete_topic, nor any prerequisite beyond the schema's mention of list_workspaces. Usage is only implied by the verb 'rename'.

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