Pineprompt

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, and the description reinforces idempotency while adding substantive behavioral context not present in structured fields: the same-project invariant and the non-obvious side effect that attaching an ignored brand clears its ignored mark. It still omits error behavior on cross-project input and any description of the response, which is where it loses a point.

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 layered with constraints and state-transition semantics in four short sentences with no filler. The idempotency sentence partially repeats the idempotentHint annotation, a minor redundancy rather than a flaw.

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

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

For a two-parameter mutation with full schema coverage and rich annotations, this covers the invariants and the meaningful side effect an agent needs. Missing only the failure mode for mismatched projects and what the call returns, neither of which is fatal given there is no output schema to explain.

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

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

Schema coverage is 100%, so both parameters are already documented, including the same-project constraint on segment_id. The description's 'own brand is implicit' remark adds a little semantic color about brand_id, but the baseline 3 is appropriate since the schema carries the weight.

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 pair ('Attach a brand to a segment') that is immediately distinguishable from its nearest sibling detach-brand-from-segment-tool and from attach-tag-to-prompt-tool. An agent knows exactly what operation this performs 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?

The description gives real context on the conditions and consequences of attachment (discovered brands start being tracked, ignored brands are revived, the own brand is a no-op), which steers usage decisions. It never names an alternative tool or states an explicit when-not case, however, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful context beyond these hints: it explains what idempotency means here ('succeeds without change') and imposes a cross-entity constraint that both prompt and tag must share a project, which is not fully conveyed by the annotations alone.

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

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

Three short sentences, front-loaded with the core action. Each sentence adds a distinct piece of information (purpose, idempotency behavior, project constraint) without redundancy or 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 simple two-parameter attach operation with no output schema and annotations covering the safety profile, the description covers purpose, idempotency, and the key same-project prerequisite. It could optionally mention failure behavior when project ownership does not match, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description reinforces the cross-parameter requirement that prompt and tag share a project, but this duplicates what the tag_id schema description already states, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: 'Attach a tag to a prompt.' The operation is unambiguous and clearly distinguishable from the sibling 'detach-tag-from-prompt-tool' by its verb, and from tag-management siblings like 'create-tag-tool'.

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

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

Provides a prerequisite ('Both the prompt and the tag must belong to the same project') and notes idempotent behavior, which implies it is safe to call even if already attached. However, it does not explicitly name or compare against alternatives such as detach-tag-from-prompt-tool or explain when to prefer other tag operations.

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 mutation profile (readOnly=false, idempotent=false, destructive=false). The description adds substantive traits: display names are unique per project case-insensitively, and a collision with an existing name or alias returns an error. It also explains that segment membership is what makes a brand a competitor, which is behavior the annotations cannot convey.

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

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

Front-loaded with the core action, then conditions and error behavior. It is dense but each clause carries distinct information (defaults, uniqueness, alternative route). Slightly long, but no sentence 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 5-param, no-output-schema mutation tool, the description covers defaults, uniqueness/error behavior, and the alternative path for designating the project's own brand. With the schema fully documenting each parameter, 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. The description goes beyond the schema by explaining the semantic consequence of `segment_ids` (membership makes a brand a competitor) and the cross-tool role of a brand id on update-project, which is not derivable from this tool's schema.

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

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

States a specific verb and resource ('Create a brand in a project') and distinguishes the outcome from the automatic discovery path ('ahead of Pineprompt discovering it from an AI response'). An agent can tell this apart from update-brand-tool and attach-brand-to-segment-tool without opening either schema.

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

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

Gives explicit conditional guidance: pass `segment_ids` to start tracking as a competitor, omit them to create as discovered, and omit aliases to seed with the display name. It also routes the own-brand case to a named alternative ('pass its id as `brand_id` on the update-project tool instead'), which is exactly the when-not/alternative guidance the dimension rewards.

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 mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=true); the description adds real behavior: an email is actually sent to an address outside the platform, acceptance expires after 14 days, owner cannot be invited, and pending invitations consume plan seat quota. These consequences (external side effect, time-bound state, quota impact) are not derivable from annotations or 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?

Four short sentences, zero filler, front-loaded with the action and then the constraints in decreasing order of importance (permissions, expiry, role limits, quota). Every sentence carries a distinct constraint.

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-required-param mutation with no output schema, the description covers permissions, external side effects, expiry, allowed roles, and quota impact — enough to call it correctly. It is silent only on edge cases such as what happens when the address already has a pending invitation, which is a minor gap given idempotentHint=false is already declared annotation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the role enum constraint, and the description's role rule duplicates it. The description adds no syntax, format, or ID discovery guidance 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?

"Invite a person to join an organization by email" gives a specific verb (invite), a specific resource (organization membership), and the mechanism (email), which cleanly separates it from the sibling delete-invitation-tool and from the create-*-tool family. 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?

The description states the precondition (admin or owner rights in the organization) and the admission rule (allowed roles admin/member, owner cannot be invited), so an agent knows when the call will succeed. It does not name an alternative or say when not to use it (e.g., how to revoke — presumably delete-invitation-tool), so it stops short of routing guidance.

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

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

Annotations already cover readOnly=false, destructive=false, idempotent=false, and openWorld=true, but the description adds valuable non-obvious context: active monitors dispatch prompts daily on Pineprompt's schedule and consume plan quota. That resource-consumption side effect is exactly the kind of behavior an agent cannot infer from annotations. Auth requirements and response behavior are still unstated.

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

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

The core purpose ('Create a new monitor for a project') is buried in the second sentence rather than front-loaded, and the quota point is made twice ('uses plan quota' and 'Subject to the organization's plan quota'). Three sentences with a redundant clause is serviceable but not tight.

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

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

For a six-parameter create tool with full schema coverage and no output schema, the description supplies the resource definition and the quota/scheduling implications an agent needs. Only the return value and permission requirements are unaddressed, which are minor gaps here.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly (country code format, platform allow-list, name length, is_active semantics). The description only loosely restates country/language/platforms without adding format or constraint detail, 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 ('Create a new monitor for a project') and explains what a monitor is: it runs prompts against one or more AI platforms in a given country and language. This differentiates it functionally from create-prompt-tool and other create siblings, though no sibling is named explicitly.

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

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

Usage is implied (create a monitor when you need to run prompts against AI platforms on a schedule) but there is no explicit when-to-use, when-not-to-use, or comparison to alternatives like update-monitor-tool or get-monitor-tool. The quota note hints at a cost constraint but does not guide tool selection.

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

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

Annotations already declare the safety profile (readOnlyHint=false write, destructiveHint=false, idempotentHint=false, openWorldHint=false), lowering the bar. The description adds genuine value beyond them by disclosing the ownership assignment and that an organization id is returned for chaining. It says nothing about failure modes such as duplicate names or permission requirements, so it stays at 3.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the useful output-chaining note. No filler, no repetition of schema contents.

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

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

For a one-parameter create tool with annotations covering the safety profile and no output schema, the description covers purpose, ownership side effect, and how to consume the returned id. Only minor gaps remain, such as duplicate-name handling or required scopes, so it is nearly complete.

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

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

Schema coverage is 100% for the single 'name' parameter, including the max-80-characters constraint, so the schema fully documents it. The description adds no parameter-level detail (e.g., uniqueness or accepted characters) beyond what the schema already states, 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?

The description uses a specific verb+resource ('Create a new organization') and adds the ownership side effect ('authenticated user as the owner'). The resource name cleanly distinguishes it from create-project-tool, create-brand-tool, and the get/list/update/delete-organization siblings. It stops short of explicitly contrasting with any sibling, so it lands at 4 rather than 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 explicit when-to-use or when-not-to-use statement, nor any named alternative. Usage is only implied by the verb 'create' and by the note that the returned id can be reused in later calls. Adequate for such a self-evident operation, but it provides no real routing guidance.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=false. The description adds a useful plan-quota failure condition, but does not mention required permissions, success behavior, or whether the created project is returned.

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

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

Two short sentences, front-loaded with the action and scope; no filler. The quota caveat follows naturally without obscuring the main instruction.

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 full schema coverage and annotations covering the safety profile, the description supplies the core action and one important constraint. It omits return value and auth details, but for a simple create operation these gaps are minor.

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

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

Schema coverage is 100%, with descriptions for both required parameters including the 120-character limit on name and the numeric type of organization_id. The description adds no additional parameter detail beyond mapping 'given organization' to organization_id, 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 ('Create'), resource ('project'), and scope ('in the given organization'), which distinguishes it from update-project, delete-project, list-projects, and get-project. The added quota constraint further clarifies the 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?

Provides no explicit when-to-use guidance, prerequisites, or alternatives. The quota note is a constraint rather than usage direction, leaving the agent to infer that this is the tool for creating a project.

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 (readOnlyHint false, openWorldHint true), but the description adds real context they cannot convey: quota is consumed by runs, active prompts are dispatched daily to third-party engines like ChatGPT/Gemini/Perplexity, and inactive prompts do not run. It does not cover duplicate-prompt behavior or what is returned on success.

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?

Short and front-loaded enough to be usable, but the plan-quota constraint is stated twice ('uses plan quota' / 'Subject to the organization's plan quota'), and the opening sentence about active prompts is slightly out of order relative to the actual action being described.

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 create tool with no output schema, the description covers the side effects (scheduling, quota, third-party dispatch) that the schema and annotations do not. It stops short of indicating the created prompt's identifier or error conditions, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema with types and constraints (max 2000 characters, numeric monitor id). The description only echoes is_active semantics ('when is_active is true'), 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?

'Create a new prompt for a monitor' gives a specific verb and resource, and the surrounding text ties the object to a monitor, plan quota, and the monitor's configured AI platforms. It is clear what the tool does, though it does not explicitly contrast itself with update-prompt-tool or any 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?

It says when the created prompt will actually fire (is_active true, on the monitor's schedule), which implies when to use it. However, there is no explicit guidance on when to reach for this versus update-prompt-tool or how it relates to the monitor lifecycle, so usage is only implied.

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

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

Annotations already mark this as a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds a real behavioral fact beyond them: duplicate names in any casing cause an error, which tells the agent the call can fail on a semantic constraint. It omits permissions/auth requirements and the success response 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?

Two tight sentences with the primary action front-loaded and the failure condition immediately after; no filler and 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?

For a simple two-parameter create tool whose annotations carry the safety profile and whose schema fully documents inputs, the description covers purpose and the key failure mode. With no output schema it could say what a successful call returns, which is the only notable gap.

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

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

Schema description coverage is 100%, so both parameters are already documented with types and the 64-character limit. The description restates the case-insensitive uniqueness rule that the schema's name description already states, adding no syntax or format detail 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+resource+scope ('Create a new segment for a project'), which cleanly separates it from update-segment-tool, delete-segment-tool, and the other create-*-tool siblings by resource. It does not name any alternative, but the intent 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?

Usage is implied by the create verb and the uniqueness rule, but there is no explicit when-to-use/when-not guidance and no mention of prerequisites (e.g., that project_id must reference an existing project) or of update-segment-tool as the alternative for modifying an existing segment.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real behavioral detail beyond them: the case-insensitive uniqueness constraint and the fact that a duplicate in any casing returns an error, which explains why the operation is not idempotent. It does not state permissions or what the call returns.

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 verb front-loaded and constraints packed into a single parenthetical. Slightly redundant with the schema descriptions, 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 3-param creation tool with full schema coverage and annotations carrying the safety profile, the description covers the essentials. It omits what the call returns (the created tag or its id) and any precondition that the project must already exist, which is a minor gap given no output schema.

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

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

Schema description coverage is 100%, so baseline is 3 — the description's parenthetical about the name being unique per project and the color coming from a preset palette largely restates what the schema already documents for those two properties. No added syntax, format, or edge-case semantics.

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

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

StartsWith a specific verb+resource: "Create a new tag for a project." The verb alone separates it from update-tag-tool, delete-tag-tool, and get-tag-tool siblings, and the scoping to a project is stated 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?

No guidance on when to choose this over alternatives — nothing about checking whether a tag already exists via list-tags-tool, or falling back to update-tag-tool rather than re-creating. The duplicate-error note is a constraint, not routing guidance.

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

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

Annotations already disclose the safety profile (destructiveHint=true, idempotentHint=true, readOnlyHint=false), so the description need not repeat it. It adds the qualifying state 'pending', but says nothing about whether accepted invitations fail or are refused, whether the cancel is soft or permanent, or what permissions are needed.

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 action and the eligible state, and zero filler. Nothing could be removed without losing information.

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

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

For a one-parameter delete tool whose annotations carry the destructive/idempotent profile, this is minimally adequate. It omits the failure mode for already-accepted invitations and any hint of the result, but with no output schema and full param coverage the gap is modest.

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 only one parameter and schema description coverage is 100%, so the schema already documents invitation_id fully. The description adds no format, range, or lookup guidance beyond that, which is the baseline 3 case.

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 (cancel) and resource (pending invitation), so an agent immediately knows this removes an invitation rather than creating or updating one. It does not explicitly name a sibling such as create-invitation-tool, so it stops short of full differentiation.

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?

'Pending' implies the eligible state for cancellation, which is a meaningful usage constraint the agent can infer. However, there is no explicit when-to-use guidance and no mention of alternatives or what to do for non-pending invitations.

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 well beyond them: it discloses that running stops immediately, that deletion is soft, that data is retained for 30 days, and only then permanently removed. This is exactly the recovery/retention context an agent needs before a destructive call.

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

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

Three sentences, front-loaded with the action, then the immediate behavioral effect, then the retention lifecycle. Every sentence adds a distinct fact 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?

The tool is simple (one required param, no output schema) and the annotations cover the safety profile. The description supplies the one thing needed and missing elsewhere: the soft-delete lifecycle and 30-day recovery window.

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 monitor_id parameter, so the schema carries the semantics. The description adds nothing about the parameter, which is the expected baseline when coverage is complete.

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 monitor') in the first two words, distinguishing it cleanly from update-monitor-tool and the other delete-*-tool 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?

Usage is implied by the delete verb and the destructive consequence, but the description never states when to reach for this tool versus alternatives like update-monitor-tool or list-monitors-tool, nor any prerequisites. Minimum viable guidance with a clear 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 flag destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: the subscription is canceled immediately (not at end of billing period), the deletion cascades to projects, monitors, and historical data, and there is a 30-day recovery window before permanent removal. This is exactly the blast-radius detail an agent needs before invoking a destructive tool.

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

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

Three short sentences, front-loaded with the action, followed by immediate and delayed consequences in ascending order of severity. No filler, every sentence 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?

For a single-parameter destructive tool with no output schema, the description covers the action, the cascade scope, the retention window, and the permanence endpoint. Nothing an agent needs to decide whether to call it 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?

Only one parameter (organization_id) and schema description coverage is 100%, so the schema already fully documents it. The description adds nothing about the parameter itself, which is acceptable at this coverage level.

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

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

States a specific verb and resource ('Delete an organization') and the scope of impact makes it unmistakably distinct from delete-project-tool, delete-monitor-tool, and the other delete siblings. No ambiguity about what entity is targeted or how far the deletion reaches.

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 conveys the gravity of the operation (immediate subscription cancellation, 30-day soft delete, permanent removal), which implicitly signals this is a last-resort action, but it never states when to use it versus update-organization-tool or any explicit preconditions/exclusions. Usage is implied by consequence rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds substantial context beyond that: monitors stop immediately, the project and its historical data are soft-deleted, retained for 30 days, then permanently removed. This clearly discloses what is destroyed and the data lifecycle.

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

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

Three sentences with zero waste: the command is front-loaded, followed by immediate consequence, then retention and permanent deletion details. 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?

The tool is simple with one fully documented parameter, annotations already cover the safety profile, and no output schema is needed. The description supplies the key behavioral details an agent needs, including cascading effects and retention period.

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 project_id parameter is fully documented in the schema. The description adds no additional meaning about the parameter, so the baseline of 3 applies.

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

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

"Delete a project" states a specific verb and resource, and the third sentence clarifies scope by saying the project and everything beneath it is affected. This distinguishes it from delete tools for sub-resources like monitors or tags, even without naming siblings.

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

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

The description explains consequences but provides no explicit when-to-use guidance, prerequisites, or alternatives such as update-project-tool or list-projects-tool. Usage is only implied by the verb 'Delete'.

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 well beyond them by disclosing the exact lifecycle: immediate stop of execution, soft-delete of the prompt AND its historical responses, 30-day retention, then permanent removal. That is precisely the 'what gets destroyed and how recoverable it is' context an agent needs before an irreversible action.

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 immediate effect, then the retention consequence. No filler and nothing repeated from the schema or annotations.

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

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

For a one-parameter mutation tool with no output schema and annotations already covering safety, the description supplies the missing behavioral layer (soft-delete window and permanent removal). Nothing an agent needs to call it correctly 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?

There is a single parameter with 100% schema description coverage ('The numeric id of the prompt to delete'), so the schema fully documents it. The description adds no syntax, format, or lookup guidance beyond the schema, 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?

States a specific verb and resource ('Delete a prompt') and immediately scopes the effect: the prompt stops running, and both the prompt and its responses are removed. This cleanly separates it from the many delete-*-tool siblings and from update-prompt-tool or get-prompt-tool.

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 intent of the tool makes its usage implied and unambiguous, and the description clarifies the consequence of calling it, but it never states when to prefer deletion over alternatives (e.g., update-prompt-tool to pause/disable) or any 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?

Goes well beyond the annotations (destructiveHint, idempotentHint), disclosing the soft-delete with 30-day retention before permanent removal, the side effect on attached brands at both the brand level and the project level, and the last-segment error. This is exactly the cascading-consequence context an agent needs before a destructive call.

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

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

Front-loads the action, then layers consequences, retention policy, and the failure condition in four dense sentences with no filler. Every sentence carries information the agent cannot get from the schema or annotations.

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

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

For a single-parameter destructive tool with no output schema, the description covers action, side effects, reversibility window, and error behavior. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and segment_id is already documented as "The numeric id of the segment to delete." The description adds no further meaning about the parameter, 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 ("Delete a segment") that is immediately distinguishable from siblings like update-segment-tool, delete-project-tool, and detach-brand-from-segment-tool. An agent knows exactly what this tool operates on 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 a clear when-not condition ("A project must keep at least one segment, so deleting the last one returns an error"), which tells the agent when the call will fail. It does not name an alternative tool for the cases where deletion is inappropriate, keeping it short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the operation is a soft delete with 30-day retention before permanent removal, and attached prompts are unaffected. It still omits auth/permission requirements and whether restoration is possible during the retention window.

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 side effect on prompts, then the lifecycle. 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?

For a one-parameter destructive tool with rich annotations and no output schema, the description covers the key agent-facing concerns: what is removed, what is not, and the retention period. Minor gaps remain around permissions and failure behavior for an already-deleted id, though idempotentHint partially covers the latter.

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 parameter (tag_id, documented as the numeric id), so the schema already does the work. The description adds no format or semantic detail beyond it, 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?

States a specific verb and resource ("Delete a tag") and immediately clarifies the effect on attached prompts, which separates it from the sibling detach-tag-from-prompt-tool. An agent can distinguish this from update-tag-tool and get-tag-tool 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?

Usage is implied by the name and the description of the delete lifecycle, but there is no explicit when-to-use vs. when-not guidance and no reference to alternatives such as detach-tag-from-prompt-tool (for removing a tag from a prompt only) or update-tag-tool. Minimum viable 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 supply destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered. The description adds real value beyond them by disclosing that this removes a membership from a specific organization (not a global account) and that the organization owner is protected from removal.

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, no filler, with the action and its scope front-loaded and the exception rule second. Every clause earns its place.

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

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

For a simple two-parameter deletion with annotations covering the safety profile and no output schema needed, the description is nearly sufficient. It leaves unstated what happens to data or memberships associated with the user and whether deleting a non-member errors.

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 required parameters are fully documented in the schema. The description adds no parameter syntax or constraints beyond what the schema already states, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Remove a user') plus the scope ('from an organization'), which separates it cleanly from delete-organization-tool and delete-invitation-tool. It stops short of explicitly naming a sibling, but the operation 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 never says when to reach for this tool versus update-user-tool or the other delete-* siblings, and offers no exclusions or preconditions for calling it. The owner rule is a constraint on the operation, not guidance on when to use it.

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

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

Adds substantial context beyond the annotations: it explains the semantic side effect (membership is what makes a brand a competitor, so detaching removes tracking and reverts the brand to `discovered` with mention history intact). It also states idempotency semantics and the own-brand restriction, none of which the annotations convey.

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

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

Four tightly packed sentences, front-loaded with the action, then idempotency, constraint, and side effect in order of importance. No filler; every sentence contributes 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 a mutation with no output schema, the description supplies the side effects, idempotency, and validity constraints an agent needs. Nothing required to invoke it correctly appears to be missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema. The description adds relational constraints (same-project requirement) but no syntax or format detail beyond the schema; 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+resource ('Detach a brand from a segment') that directly and unambiguously distinguishes it from the sibling attach-brand-to-segment-tool. An agent can select it 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 preconditions ('both the brand and the segment must belong to the same project') and a hard exclusion ('the own brand is implicit in every segment and cannot be detached'). It does not explicitly route to the attach counterpart, but the usage context is clear.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, yet the description earns credit by elaborating what idempotency means here (detaching an unattached tag succeeds without error) and by adding a precondition not present in structured fields — the same-project scoping requirement. It does not spell out the error surface for cross-project attempts, 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?

Three short sentences, front-loaded with the action, then the idempotency guarantee, then the precondition. 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?

For a two-parameter mutation with no output schema and annotations covering the safety profile, the description supplies the operation, the idempotency semantics, and the project constraint. It is nearly complete; only failure behavior for cross-project inputs is left implicit.

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%, with both prompt_id and tag_id individually documented as numeric ids. The description adds no parameter-level 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 ("Detach a tag from a prompt") that is inherently distinguishable from its inverse sibling attach-tag-to-prompt-tool. An agent knows exactly what operation this performs 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?

The description gives an implicit precondition (both prompt and tag must belong to the same project), which helps the agent decide when the call is valid. However, it never explicitly names the alternative tool (attach-tag-to-prompt-tool) or states when-not to use this. Usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the notion that `include` can pull in parent chains; it says nothing about what happens when the id is not found or how large the returned payload can become.

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 tightly scoped sentences with the core action front-loaded and no filler. The second sentence is slightly wordy ("If you would like to ... you may pass") but still 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 two-parameter read tool with full schema coverage and annotations covering the safety profile, the description is nearly sufficient. The one gap is that no output shape is described, though the absence of an output schema makes that a minor omission.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining the purpose of `include` (embedding the pointed-to brand or a deeper parent chain) rather than merely restating the whitelist. That rationale goes beyond the schema's enum of allowed values.

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

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

The description states a specific verb and resource: "Fetch a single brand mention by its numeric id," which is clearly distinct from list-brand-mentions-tool by the word "single." It does not name the sibling list tool explicitly, so it falls just 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?

It gives conditional guidance for the optional `include` parameter, but says nothing about when to prefer this over list-brand-mentions-tool or get-response-tool, and offers no exclusions. Usage is implied rather than directed.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is fully covered. The description adds only that include 'loads parent chains', which is mild extra context; it says nothing about missing-id errors or auth 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?

Two short sentences, zero filler, with the primary action (fetch by id) front-loaded before the optional parameter. 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?

Adequate for a simple get-by-id tool, but with no output schema the description does not describe the returned citation shape, and it omits error behavior when the id does not exist. These gaps are minor but real for a fetch tool.

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

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

Schema description coverage is 100%, including the full whitelist of include values, so the schema carries the parameter documentation. The description only restates include's purpose ('load parent chains'), adding a little meaning but no syntax or format detail.

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 ('Fetch a single citation by its numeric id'), which cleanly separates it from the sibling list-citations-tool by cardinality. It does not name that sibling explicitly, so an agent must infer the single-vs-list distinction.

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

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

Usage is only implied: 'by its numeric id' signals a lookup when you already know the id, and the include clause hints at when to request related data. No alternative tool is named and no condition for choosing this over list-citations-tool is stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by explaining that `include` expands the payload to load the parent project chain, which tells the agent the operation can change in cost/scope.

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 compact sentences, front-loaded with the primary action and id requirement, followed by the optional expansion. Nothing redundant or 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?

For a simple 2-parameter read tool with a fully documented schema and annotations covering safety, the description tells the agent what it fetches and what include adds. No output schema exists, but the single-monitor return shape is sufficiently implied.

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 schema already defines both parameters and the include whitelist. The description still adds semantic meaning by stating that `project.organization` loads the parent chain, going slightly beyond the schema's flat enumeration.

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?

Clear verb+resource ('Fetch a single monitor') with the key constraint (by its numeric id) that distinguishes it from list-monitors-tool. It does not name a sibling explicitly, but the 'single' vs. listable distinction 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?

Usage is implied: use this when you have a monitor id and want one record. The description never states when to prefer list-monitors-tool or when this tool should not be used, so an agent must infer the 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that – no behavior on a missing/nonexistent id, no permission requirements, no note on what a returned organization contains.

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 verb and lookup key front-loaded and zero filler. It is appropriately sized for a trivial single-entity read, though it provides no structure beyond the one 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 one-parameter read tool with complete schema coverage and full annotation coverage, the definition is workable but thin: it says nothing about failure/not-found behavior and, with no output schema present, nothing about what the fetched organization yields.

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 parameter is documented in the schema as "The numeric id of the organization to fetch." The description's "numeric id" merely restates it, adding no format, range, or sourcing guidance.

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

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

Names a specific verb ("Fetch") and resource ("a single organization") plus the key (numeric id), which cleanly separates it from list-organizations-tool, update-organization-tool, and delete-organization-tool. It does not explicitly name any sibling as the alternative, so it falls just 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?

Usage is only implied: the phrase "by its numeric id" signals that this is the tool to reach for when the id is already known and the list tool would be wasteful. There are no explicit when-to-use/when-not statements, no mention of list-organizations-tool as the alternative, and no prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the null-per-bucket rule for brands without mentions in a bucket, the default 20 / max 50 cap, and the ordering semantics that explain how values are produced.

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

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

Four tight sentences, front-loaded with what the metric is before covering scoping and edge cases. No filler, no restatement of the tool name, and each 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?

With no output schema, the description does the work of explaining the returned shape (a per-bucket value per brand series, null when no mentions), which is what an agent needs. The interval parameter is documented only in the schema, and the description never mentions the temporal bucketing that is central to a time-series tool, which is a modest 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 coverage is 100%, so the baseline is 3; the description still adds meaning the schema does not, by explaining how brand_id, segments, and top_n interact (mutually exclusive scoping modes and fallback behavior). Default and max values for top_n are restated, which is mildly redundant with the schema.

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

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

The description names the specific metric ('average position of each tracked brand ... per bucket') and defines what position means (brand order in an answer, lower = more prominent, 1 = first named). This clearly separates it from the other time-series siblings by resource. It stops short of explicitly contrasting itself with get-visibility-time-series-tool or get-share-of-voice-time-series-tool, which is the only thing keeping it from 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?

The scoping sentence ('Scope by `brand_id` for one line; by `segments` ...; otherwise top `top_n`') is genuinely useful mode-selection guidance. However, it never says when to reach for this tool over the sibling time-series tools (sentiment, share of voice, visibility), so routing guidance is implied at best.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds only one behavioral detail beyond that – that include pulls in the parent organization – and says nothing about permissions, error behavior, or response 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?

Two short sentences, front-loaded with the core action, with zero filler. Every clause carries information an agent can use.

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 annotation coverage, a complete schema, and no output schema to explain, the description is sufficient to invoke it correctly. Slightly more context on the include semantics or failure modes would make it airtight.

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 in the schema, including the whitelist for include. The description largely restates that include loads the parent organization, adding little beyond the structured data.

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 (fetch) and resource (a single project) and scopes it with 'by its numeric id', which implicitly separates it from list-projects-tool. It does not explicitly name the sibling, but the singular framing makes the distinction clear without opening a schema.

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

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

Usage is only implied: 'a single project' versus the list counterpart tells the agent when this tool is appropriate. There is no explicit when-to-use/when-not statement and no mention of alternatives such as list-projects-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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the notable behavior that `include` expands the parent monitor/project/organization chain, but says nothing about error behavior for a missing id or the response shape otherwise.

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

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

Two short sentences with the fetch action front-loaded and zero filler. The optional include behavior is correctly relegated to the second sentence.

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

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

For a 2-param read with no output schema, the description covers the input behavior but does not describe what a fetched prompt looks like or what happens when the id does not exist. Annotations carry the safety profile, so the gap is moderate rather than severe.

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 in the schema, including the whitelisted `include` values. The description restates the include-expansion effect without adding syntax or format detail beyond the schema, so baseline 3 is appropriate.

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

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

'Fetch a single prompt by its numeric id' pairs a specific verb with a specific resource and implies the singular-fetch role against the list-prompts-tool sibling. It stops short of explicitly naming or contrasting that sibling, so it lands at clear-but-undifferentiated.

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

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

Usage is only implied by 'single prompt' – an agent can infer you call this when you already have an id rather than when browsing. No explicit when-to-use, prerequisites, or when-to-prefer-list-prompts-tool is stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior: `include` pulls parent chains, and brand mentions/citations are deliberately absent from the payload, which is exactly the kind of omission an agent would otherwise discover by failure.

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, zero filler, and the core fetch semantics are front-loaded before the two caveats. Every sentence carries information the agent needs.

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

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

No output schema exists, so the description carries some of the return-shape burden, and it does address that partially by disclosing what is not embedded. It stops short of describing the response envelope or pagination, but for a two-parameter single-fetch tool with full schema coverage this is nearly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema's enumeration by characterizing `include` as loading 'parent chains' — explaining the intent of the whitelisted traversal rather than just listing resource names.

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

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

Specific verb (fetch) plus resource (a single AI response) and a stated key (numeric id). It is clearly the singular counterpart to the sibling list-responses-tool, so the agent can distinguish them without opening a schema.

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

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

It states when to use `include` (to load parent chains) and explicitly routes brand mentions and citations to `/v1/brand-mentions` and `/v1/citations` rather than this tool. That is real routing guidance, though it never states the condition for choosing this tool over list-responses-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=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds the mild behavioral note that `include` expands the response with the parent project chain, but says nothing about error behavior or auth needs; with annotations bearing the load, a 3 is appropriate.

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

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

Two short sentences, zero waste, with the core fetch action front-loaded before the optional parameter note. 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 single-resource read with full annotation coverage, a complete schema, and no output schema requirement, the description supplies what an agent needs to invoke it correctly. Only minor gaps remain, such as not explaining the shape of the expanded response.

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

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

Schema description coverage is 100% and both parameters are documented in the schema itself, including the whitelisted `include` values. The description restates the `include` effect ('load the parent project chain') at a high level, adding only marginal meaning over the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Fetch a single segment by its numeric id'), clearly separating it from list-segments-tool and the mutation tools. It does not explicitly name a sibling to route the agent, but the singular scope plus id requirement makes the intent 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?

It mentions that `include` may be optionally passed to load the parent project chain, which implies one usage pattern, but there is no guidance on when to prefer this tool over list-segments-tool or when `include` is worth the extra payload. Usage is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety bar is low. The description still adds real behavioral context beyond them: the null value for brands with no mentions in a bucket, plus the top_n default (20) and cap (50).

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, zero filler, with the metric and scope front-loaded before the fallback rules and the null edge case. 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?

With no output schema, the description must describe the return: it gives the metric's unit range and the per-bucket null convention. It omits the required interval granularity and the overall list-of-series shape, minor gaps against a 100%-covered schema and full annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the interaction semantics the schema lacks: how brand_id, segments, and top_n compete as scoping mechanisms and which wins when unset. It does not add detail on tags/monitors/countries/platforms, which the schema already covers.

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 precise metric and scope: 'Average sentiment score (0-100) of each tracked brand's mentions per bucket.' The verb/resource (sentiment per bucket) inherently distinguishes it from the position, share-of-voice, and visibility time-series siblings, so an agent can select it 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?

Explicitly defines the three scoping modes: brand_id for a single line, segments for a segment's brands, otherwise top_n by mention count. This tells the agent how to drive the tool, though it names no alternative tool and gives no 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 read-only/idempotent/ non-destructive safety profile, and the description adds meaningful behavior beyond that: the single-brand line reads 100, and notably that the top_n cap never affects the denominator. That denominator caveat is a genuine behavioral disclosure not present in 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?

Three sentences, front-loaded with the metric definition before the scoping rules. Dense but every clause carries information; the parenthetical default/max is compact.

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 but 100% parameter description coverage and read-only annotations, the description is nearly complete for a read analytics tool. It covers the non-obvious scope/cap logic; only the temporal interval semantics are left entirely to the schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: what a brand_id-scoped result reads (100 in buckets with mentions) and the default/max/cap-doesn't-affect-denominator behavior of top_n. This meaningfully deepens interpretation of the key scope parameters.

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

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

Clearly states the specific metric computed: each brand's mentions as a percentage of scoped brands' mentions, per bucket. A specific verb+resource+computation is defined, though it does not explicitly differentiate itself from metric siblings like get-visibility-time-series-tool or get-sentiment-time-series-tool.

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

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

It explains how scoping choices (brand_id, segments, otherwise top_n) change the result, which implies usage, but never states when to choose this tool over its time-series siblings. The guidance is about parameter effects rather than tool selection.

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

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

Annotations already declare this a read-only, idempotent, non-destructive operation, lowering the bar. The description contributes by explaining that `include` traverses the parent project chain, but it omits what happens on a missing/invalid id or what the response shape looks like.

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 zero waste; the core action is front-loaded before the optional parameter note.

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-record read with full schema coverage and safety annotations, the description is nearly sufficient. A note on behavior when the id is absent would complete it, 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 coverage is 100%, so the schema already documents both parameters including the include whitelist. The description adds only marginal framing ('load the parent project chain'), so it earns the baseline 3 rather than more.

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 (Fetch) and resource (a single source) scoped by numeric id, which implicitly contrasts with the list-sources sibling. It does not explicitly name list-sources-tool or get-project-tool, so differentiation relies on inference.

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 single-record framing implies the appropriate context (fetch one source when you have its id), but there is no explicit when-to-use-vs-alternative guidance, no mention of when to prefer list-sources-tool, and no prerequisites stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral value beyond that: unbounded (non-paginated) output and a one-row-per-enum-value result shape, which tells the agent what volume/format to expect. It does not mention auth or rate limits, but those are not implied needs 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?

Three short clauses, front-loaded with what the tool returns, then the pagination behavior, then the scoping limit. Zero wasted words.

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 aggregate analytics tool with no output schema, it discloses the shape and cardinality of results and a key scoping restriction. It stops short of stating that this is an aggregate (not time-series) tool, which the interval parameter's 'ignored for aggregate tools' note leaves slightly ambiguous.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including the required date range and filters. The description adds only the segment-scoping caveat, which is informative but not parameter syntax; 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: citation breakdown by source-type classification, with examples (blog, news, forum). It is clearly distinguishable from sibling list-source-analytics-tool and get-source-url-type-analytics-tool in spirit, though it does not name them 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?

Provides one exclusion ('Cannot be scoped by segment'), which is genuine when-not guidance, but names no alternative tools and gives no positive trigger for choosing this over the sibling source/url-type analytics tools.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavior beyond them: the result is unpaginated with exactly one row per URL-type enum value, and segment scoping is unsupported. It stops short of describing the metrics/fields returned.

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 with zero filler, front-loading what the tool computes before the two operational constraints. Every clause earns its place.

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

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

For an 8-parameter aggregate tool with full schema coverage and a strong annotation set, the description supplies the key return-shape and scoping facts an agent needs. The only meaningful gap is the lack of routing guidance relative to the similarly-named source-type and source-url analytics siblings.

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 in the schema and the baseline is 3. The description adds no syntax, format, or default details about parameters (it never references tags, monitors, platforms, interval, etc.), so it does not exceed the schema's contribution.

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: 'Citation breakdown by URL-type classification,' with concrete examples of the classification values (article, documentation, product_page). It is clear what the tool returns, but it never differentiates itself from the closely-named sibling get-source-type-analytics-tool or from list-source-url-analytics-tool, which an agent must disambiguate on its own.

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 constraints ('Unpaginated', 'Cannot be scoped by segment') that imply when this tool is and isn't appropriate, but it never names an alternative or states the positive condition under which an agent should pick this over the sibling source-type or source-url analytics tools. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the useful behavioral detail that output is bucketed time-series data capped to top_n URLs (default 20, max 50), but says nothing about the required interval granularity or result 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?

Two tight sentences that front-load the metric definition before the cap constraint. No filler, though the second sentence largely duplicates schema content already stated in top_n's description.

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, time-series analytics tool with no output schema, the description covers the metric and the cap but omits the bucketing/interval requirement, sibling differentiation, and any note on filters (tags, monitors, countries, platforms). Annotations carry the safety profile, but the functional description is thinner than the tool's complexity warrants.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters including top_n's default/max and interval's allowed values. The description only restates the top_n cap, adding no meaning beyond the schema, 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?

The description names a specific metric ('percentage of analyzed responses that cited that exact URL') per top URL over time buckets, which is a clear verb+resource definition. However, it does not distinguish itself from close siblings like get-source-usage-time-series-tool or get-source-url-type-analytics-tool, so an agent must infer the boundary.

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, no conditions that select this tool over the many sibling time-series/analytics tools, and no note that interval is required for time-series results. The only usage-flavored content is the top_n cap, which is parameter documentation rather than routing guidance.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds the capping behavior (top_n default 20, max 50), which is useful, but says nothing about auth requirements, rate limits, or pagination. Modest added value over 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 with no waste, and the core metric definition is front-loaded ahead of the top_n cap detail. Efficient and readable.

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 helpfully explains what each datapoint represents (percentage of analyzed responses citing a source per bucket). It does not explain the interval requirement or return structure more fully, but it is adequate for a read-only analytics tool.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters thoroughly. The description only restates the top_n cap, adding no syntax or format detail beyond the schema. Baseline 3 is appropriate 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 computed metric: the percentage of analyzed responses per bucket that cited any URL from each top source. Verb/resource/scope are clear, and it is distinguishable from get-source-url-usage-time-series-tool (per-source vs per-URL). It stops short of naming that sibling explicitly, so it's a 4 rather than 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?

No explicit when-to-use or when-not guidance, and it never mentions alternatives like the URL-level or analytics (non-time-series) siblings. Usage is only implied by the time-series framing and the 'bucket' language; the interval requirement is stated 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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one behavioral detail beyond that — that include expands the response to the parent project chain — but says nothing about behavior when the id does not resolve or about response 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?

Two short sentences with the core operation front-loaded and no filler; the optional parameter is mentioned second, matching its lower priority.

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

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

For a read-only single-fetch tool with a fully described two-parameter schema and annotations covering safety, the description is essentially complete; there is no output schema to explain. Only error/not-found behavior is unaddressed, a minor gap.

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

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

Schema description coverage is 100%, so tag_id and the include whitelist are already documented in the schema. The description restates include's intent ('load the parent project chain'), adding only mild extra meaning over the schema's own wording, 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 ('Fetch a single tag') plus the lookup key ('by its numeric id'), which cleanly separates it from list-tags-tool without needing to open either schema. An agent can identify the operation at a glance.

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 phrasing ('pass include to load the parent project chain'), which gives a reason to use the optional parameter, but there is no explicit when-to-use vs when-to-use-list guidance or prerequisite/permission context. Adequate but leaves the agent to infer the selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds genuine behavioral context the annotations don't: the computed metric is a mention share per brand and the output is bucketed by interval, plus the default/max on top_n. It stops short of describing return shape or empty-result 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?

Two dense sentences with no filler, front-loading the core metric before the scoping rules. Every clause carries information about either computation or parameter behavior.

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

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

With 11 params at full schema coverage and capped top_n, the structured data carries most detail. The description covers the core metric and scoping logic, and no output schema exists to defer to, but it omits any indication of the returned series format. Acceptable but not exhaustive for an analytics endpoint.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above that by explaining the interaction between brand_id, segments and top_n – a mutually-exclusive scoping priority that the individual schema descriptions do not express on their own.

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 – the share of analyzed responses mentioning each tracked brand, bucketed by interval. However, despite close siblings such as get-share-of-voice-time-series-tool and get-brand-mention-tool, it offers no explicit differentiation, so an agent cannot cleanly separate this from its near-neighbors.

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

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

It explains how scoping works (brand_id for one line, segments for segment brands, otherwise top_n), which implies intended usage, but never states when to choose this tool over the sibling time-series analytics tools. Usage is inferable rather than explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the row semantics: one row per tracked brand, zero-filled visibility/share-of-voice for brands with no mentions, and null sentiment/position. This is real behavioral detail beyond the annotations, though pagination is only gestured at ('Paginated') without cursor/page mechanics.

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: metric set first, then row semantics, then pagination. No filler, and the most decision-relevant information is front-loaded.

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

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

For a 13-parameter read-only aggregate tool with a fully documented schema and no output schema, the description covers the metric set, per-row behavior, and null/zero handling well. The main gap is filter-interaction guidance (how segments/tags/countries narrow the aggregates) and concrete pagination behavior.

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

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

Schema coverage is 100%, so every one of the 13 parameters is already documented in the schema; the description adds only the vague notion of a 'filter window'. It does not clarify how filters like segments, tags, or monitors combine, so it is baseline-level for a high-coverage 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 (per-brand aggregates) and resource (brands), and enumerates the metrics returned: visibility, share-of-voice, sentiment, position. It implicitly separates itself from the time-series and monitor/prompt/source analytics siblings via the 'per-brand' framing, but never names an alternative, so an agent must infer the distinction.

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 and no mention of alternatives despite many adjacent analytics siblings (list-monitor-analytics-tool, list-prompt-analytics-tool, get-*-time-series-tool). The reader must infer that aggregate-per-brand is wanted rather than a time series or a different entity dimension.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful behavior beyond that: newest-first ordering, a hard page-size cap of 50, cursor-following semantics, and that `include` triggers loading of parent chains — details the annotations cannot express.

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, each carrying distinct information (scope/ordering, pagination contract, optional expansion), with the core action front-loaded. No filler or restated title text.

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

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

There is no output schema, so the description carries the burden of return-value context; it does cover the page size and the nextCursor contract, but says nothing about the shape or fields of an individual brand mention. For a five-parameter, one-required list tool the coverage is good but not exhaustive.

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

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

Schema description coverage is 100%, so the schema already documents cursor, include, brand_id, project_id and response_id. The description only restates the include behavior at a high level ('load parent chains (response, brand, project, organization)'), adding marginal meaning over the schema's whitelist. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (brand mentions) scoped to a project, and adds ordering (newest first). This clearly separates it from the singular get-brand-mention-tool and from other list-* siblings such as list-citations-tool and list-responses-tool.

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 real procedural guidance — paginate via nextCursor, optionally pass include to expand parent chains — but never states when to choose this tool over alternatives (e.g. get-brand-mention-tool for a single mention, or list-citations-tool for sources). Usage is implied from the resource name rather than stated with conditions 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 the read-only, idempotent, non-destructive profile, so the safety burden is lifted. The description adds real value beyond that: ordering (newest first), a hard page cap of 50, and the `include` expansion behavior for the parent project chain.

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 with zero filler; the core scope and ordering lead, followed immediately by pagination and the optional expansion. 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?

With no output schema, the description usefully covers return size and pagination mechanics, and the annotations carry the safety profile. It does not describe the brand object fields returned, which is a minor gap for a list endpoint.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description reinforces `include`'s purpose (loading the parent project chain) but adds no syntax or format detail the schema lacks, 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 with scope ("List the brands configured for a project"), which is enough to distinguish it from sibling list-brand-analytics-tool and list-brand-mentions-tool by resource meaning. It stops short of explicitly naming or excluding those siblings, so it lands just under 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?

It gives operational guidance for pagination (omit `cursor` initially, follow `nextCursor`) but says nothing about when to choose this tool over the brand-analytics or brand-mention siblings. Usage is implied by the required `project_id` rather than stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real behavioral facts: newest-first ordering, a hard 50-per-page cap, and cursor-based continuation. It stops short of stating whether a total count or empty-page signal exists, so not a 5.

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

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

Three tight sentences with zero filler; the core purpose, ordering and pagination constraints come first, and the optional include behavior is deferred to the end where it belongs.

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 return payload (URL plus domain per citation) and pagination mechanics, which is the key missing structure. It omits any mention of the response_id filter, a slight gap for a four-parameter tool, but everything needed to call it correctly is present.

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

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

Schema description coverage is 100%, so the schema already documents cursor, include, project_id and response_id, and the description largely echoes that (include loading parent chains, nextCursor as the continuation token). It adds no syntax or format detail beyond the schema, 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 ('List the citations collected across a project') plus scope (whole project) and ordering ('newest first'). An agent can distinguish it from get-citation-tool purely from the description, and knows it returns citations rather than aggregate analytics.

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 project-scoped framing and the pagination instruction ('follow nextCursor to fetch additional pages'), which is actionable procedural guidance. However, it names no alternative (e.g., get-citation-tool for one citation) and gives no when-not-to-use condition or prerequisite for having a valid project_id.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only 'Paginated' as behavioral context, which is genuinely useful but modest. No mention of rate limits, aggregation windows, or empty-result 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?

Two terse sentences, zero filler, with the resource/scope front-loaded before the pagination note. Every clause earns its place.

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

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

For a read-only aggregate tool with no output schema, the description conveys resource, scope, metrics, and pagination, and the schema carries all 14 parameters. The main gap is the absence of routing guidance against the many sibling analytics tools, which matters in a tool set this large.

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 14 fully documented parameters, so the baseline is 3. The description's mention of visibility/share-of-voice/sentiment/position mirrors the schema's sort_by values but adds no syntax or format detail 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+resource ('per-monitor aggregates') and names the four metrics returned, plus the brand scoping. 'Per-monitor' distinguishes it from the sibling per-brand/per-platform/per-prompt analytics tools. It stops short of naming those siblings explicitly, so it earns 4 rather than 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?

The description implies a scope ('scoped to a single brand') but gives no when-to-use guidance and never names alternatives like list-brand-analytics-tool or the get-*-time-series-tools. An agent must infer from the name alone when this aggregate tool is preferable to a time-series 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: page size of 50, the nextCursor follow-up loop, and that `include` expands the parent project chain. It stops short of describing the monitor object or total/result-count behavior, which matters since no output schema exists.

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

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

Three sentences, each earning its place: scope, pagination contract, optional expansion. The most important information (what is listed, and for what resource) is front-loaded 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 read-only list tool with full schema coverage and annotations covering safety, the description supplies the missing pagination and expansion contract that the absent output schema would otherwise have to carry. Only the shape of an individual monitor record is left unstated, which is a minor gap.

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

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

Schema description coverage is 100%, so cursor, include and project_id are already fully documented. The description's mention of `include` loading 'project, project.organization' restates the schema whitelist rather than adding meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the monitors') scoped to a project, plus an ordering guarantee ('newest first'). This cleanly separates it from get-monitor-tool (single monitor) and list-monitor-analytics-tool (aggregate metrics), so an agent can select it without opening a schema.

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

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

The description implies when the tool applies (listing configured monitors for a known project) and gives pagination mechanics, but never names an alternative or states when NOT to use it, e.g. versus get-monitor-tool or list-monitor-analytics-tool. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: a hard 50-item page cap, cursor-based continuation, result ordering, and the fields present in each item. That is meaningful disclosure for a read tool.

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

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

Three tight sentences: what it lists and ordering first, then pagination mechanics, then the role it plays in the workflow. Nothing is redundant and the most important routing hint is placed last as an actionable instruction.

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

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

There is no output schema, yet the description names the returned fields (id, name, user role) and explains the pagination contract, which is exactly the information needed to consume results. For a one-parameter read tool this is sufficient.

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 `cursor` param is fully documented in the schema. The description restates the continuation flow ('follow nextCursor'), which is mildly useful but adds no syntax or format detail beyond what the schema already supplies, 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 the organizations you belong to') plus a scope qualifier ('you belong to', newest-first ordering). An agent can distinguish it from get-organization-tool, create-organization-tool, and delete-organization-tool without consulting schemas.

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

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

Explicitly frames the tool as the entry point for discovering ids needed by other tools, which is genuine routing guidance in a 60+ sibling environment. It stops short of naming a specific alternative or an exclusion, so it misses the top band.

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 safe read-only, idempotent, closed-world profile. The description adds genuine behavioral context beyond that: the return shape (one row per platform present in the filtered response set) and the ordering (sorted by visibility desc). It omits pagination/limits, 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 dense sentences, front-loaded with the resource scope and followed by the row/sort semantics. Every clause carries information; nothing is repeated from the name or annotations.

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

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

With no output schema, the description usefully covers the return value (per-platform rows with named metrics, sorted by visibility). Annotations handle safety and the 10-param schema is fully documented. The only real gap is the absence of any routing guidance among the many analytics siblings.

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 (tags, monitors, segments, countries, platforms, dates, interval) is already documented in the schema. The description's 'filtered response set' hints that the optional filters apply, but adds no syntax or semantics beyond what the schema supplies. 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 resource and scope: 'Per-AI-platform aggregates' with an explicit metric list (visibility, share-of-voice, sentiment, position, used_count) scoped to a single brand. The 'per-AI-platform' framing distinguishes it from the other list-*-analytics siblings, though it never names an alternative directly.

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 when-to-use guidance is provided. The agent is not told how this differs from list-brand-analytics-tool, list-monitor-analytics-tool, list-prompt-analytics-tool, or the get-*-time-series tools, nor when this aggregate view is preferred over them. Only the 'aggregate' framing implicitly signals non-time-series usage.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral detail beyond that: result ordering (newest first), a hard page size cap (50), and the cursor-following protocol. It stops short of describing what happens when the organization has no projects or how the included organization is embedded.

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

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

Two sentences with zero filler. The core purpose and ordering come first, pagination mechanics second, and the optional parameter last — a clean front-loaded structure.

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 read-only list tool with no output schema, the description covers what an agent needs: scope, ordering, page size, how to continue paging, and the optional expansion. Nothing required to call it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the `include` whitelist and the cursor protocol. The description's mention of `include` ('load the parent organization') largely restates the schema's 'Whitelisted: organization' and adds no format or syntax detail. 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 ('List the projects'), scopes it ('within an organization'), and adds an ordering guarantee ('newest first'). An agent can immediately distinguish this from get-project-tool (single project) and list-organizations-tool (different resource) 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?

The description gives operational usage for pagination (omit cursor on first call, follow nextCursor) and notes `include` is optional, which is helpful context. However, it never states when to choose this tool over siblings such as get-project-tool for a single project, nor any prerequisites or exclusions. Usage is implied rather than guided.

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 safe read-only, idempotent, non-destructive profile, so the description is free to add value elsewhere — and it does, disclosing the pagination contract ('request the next page', total under meta.last_page) and an extra return element (distinct tracked brands mentioned per prompt). With no output schema, that return-shape disclosure is genuinely useful; only rate limits or result-size caveats are absent.

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 what the tool returns and then with the pagination mechanics; nothing is wasted. The standalone fragment 'Paginated.' and the following sentence both cover pagination, a minor redundancy that costs it a point.

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

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

For a 14-parameter, read-only analytics tool with no output schema, the description covers the essential gaps: what is returned, that results are paginated, and how to advance pages and read totals. Annotations carry the safety profile, and parameters are fully documented in the schema, so nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters, including defaults, formats, and allowed sort keys. The description only reinforces the brand scoping implied by the required brand_id; it adds no syntax or format detail beyond the schema, which is the expected baseline here.

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 (per-prompt aggregates) and enumerates the four metrics returned, plus the scope (single brand). It does not explicitly differentiate itself from the many sibling analytics tools (list-brand-analytics-tool, list-monitor-analytics-tool, list-platform-analytics-tool, list-source-url-prompt-analytics-tool), so an agent must infer the grain 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?

Usage is implied by the described content — the per-prompt grain is stated, so an agent can guess when it applies — but there is no explicit when-to-use, when-not-to-use, or named alternative among the sibling analytics tools. The only procedural guidance offered is pagination.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely useful behavioral traits beyond them: newest-first ordering and a hard 50-per-page cap with nextCursor paging. It stops short of describing response shape, but these details materially help an agent call it correctly.

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

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

Three tight sentences, front-loaded with the purpose, then pagination, then the optional parameter. 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 paginated list tool with no output schema, the description covers purpose, page size, cursor mechanics, and the optional include expansion. Combined with the safety annotations and fully documented schema, an agent has everything 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 coverage is 100%, so the baseline is 3. The description goes slightly beyond by explaining the intent of `include` (loading the parent monitor/project/organization chain) and the cursor flow, which enriches the raw whitelist the schema already provides.

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

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

States a specific verb and resource with scope: 'List the prompts configured for a monitor.' This distinguishes it from analytics-style siblings but never explicitly names an alternative like list-prompt-analytics-tool or get-prompt-tool, so differentiation is inferred rather than stated.

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 purpose (listing prompts under a monitor), but there is no explicit when-to-use guidance, no conditions, and no exclusions relative to sibling list/get tools. The pagination instructions describe how to call it, not when to choose it over alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description is freed to add runtime behavior: newest-first ordering, a 50-per-page cap, and the `nextCursor` follow-up mechanism. It also discloses what is NOT returned inline (brand mentions, citations). No contradictions with 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 primary action and ordering, then pagination, then filters, then the cross-reference caveat. Every sentence carries distinct information with no 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 read-only list tool with no output schema, the description covers ordering, page size, pagination continuation, filter options, include semantics, and cross-resource redirection. It is nearly complete, though it could note whether responses include citation/brand-mention ids to link back to the separate endpoints.

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 it: it clarifies that `prompt_id` and `source_url_id` are filters, and that `include` loads parent chains (prompt, monitor, project, organization). That parent-chain explanation enriches the include parameter beyond the schema's enum-style list.

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 the AI responses collected for a project") plus the default ordering (newest first), which distinguishes it from the singular get-response-tool. It also explicitly separates itself from list-brand-mentions-tool and list-citations-tool by noting those resources are not embedded.

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 guidance: pass `prompt_id` for a single prompt's responses, `source_url_id` for responses citing a URL, and query the brand-mentions/citations endpoints for those related resources. No explicit "when not to use" or pointer to get-response-tool for single fetches, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds genuinely new behavior: page size cap of 50, the nextCursor paging contract, newest-first ordering, and that `include` expands the parent project chain.

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, no filler, with the core purpose front-loaded and pagination details following. Every sentence carries distinct information.

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

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

There is no output schema, so the description correctly compensates by describing the paginated return shape (50 per page, nextCursor) and the include-driven response expansion. An agent can call this correctly without further guessing.

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 by characterizing the output ordering and clarifying that `include` loads the parent chain rather than just naming resources. The cursor explanation largely duplicates the schema.

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

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

States a specific verb and resource ('List the segments configured for a project') plus a scope detail (newest first), which cleanly separates it from get-segment-tool and the create/update/delete siblings. It stops short of naming the alternative list tools explicitly, so it's clear but not sibling-differentiating in the strongest sense.

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 practical calling guidance (up to 50 per page, follow `nextCursor` for more) and marks `include` as optional, which is implied usage context. It never states when to prefer this over get-segment-tool for a single segment or list-projects for the parent chain, so exclusions are absent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that results are windowed aggregates and paginated, which is useful, but it does not state ordering behavior, default sort, or how empty windows are handled.

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

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

Two sentences, front-loaded with the core computation and closed with the pagination trait. No filler and nothing misplaced.

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 12-parameter, read-only aggregate tool with full schema coverage, no output schema, and complete annotations, the description explains what the returned rows represent (per-domain citation percentage and average citations), which is the key missing piece absent an output schema. It omits any mention of the filtering dimensions, but those are fully documented in the schema.

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

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

Schema description coverage is 100% across all 12 parameters, so the schema already documents dates, pagination, sort keys, and filters. The description only echoes the date window ('in the window') and pagination, adding no syntax or semantics beyond the schema. Baseline 3 applies.

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

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

The description states a specific computation: per-domain citation share (percentage of analyzed responses citing each domain) and average citations per response. This is a clear verb+resource. However, it does not distinguish itself from the crowded analytics siblings (list-source-url-analytics-tool, get-source-type-analytics-tool, list-brand-analytics-tool), which an agent could easily confuse it with.

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 or when-not-to-use guidance. With roughly a dozen sibling analytics tools that group the same underlying responses by different dimensions (source, source URL, source type, platform, prompt, brand, monitor), the description gives the agent no signal for choosing this tool over the alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety bar is low. The description still adds real behavioral context beyond them: a 50-item page cap, the nextCursor follow-up loop, and the fact that `include` loads the parent project chain. It does not describe failure or auth behavior, keeping it out of 5 territory.

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, zero filler, with the core purpose front-loaded before pagination and the optional include parameter. Every sentence carries information an agent needs to call the tool.

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

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

With no output schema, the description carries return-value burden and does so partially: it names the returned entity (cited sources) and ordering (by domain) plus pagination. An agent knows what comes back and how to page, though richer result-shape detail 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 all three parameters (cursor, include, project_id) are already documented in the schema — baseline is 3. The description reinforces nextCursor and include but adds no syntax or meaning the schema lacks.

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 ('sources cited by AI platforms when responding to a project's prompts') with an explicit ordering ('by domain'). Clear on its own, but does not distinguish itself from close siblings like list-citations-tool or list-source-analytics-tool, 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?

Usage is implied by the scope phrase ('sources cited by AI platforms when responding to a project's prompts') and the optional `include` for the parent project chain, but there is no explicit when-to-use/when-not guidance and no naming of alternatives in a sibling set dense with other list-* source tools.

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

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

The annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by stating that results are paginated and by defining the aggregate metrics, but it does not disclose authentication requirements, rate limits, or other operational constraints.

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

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

The description is two short sentences with no waste. It front-loads the core aggregate definition and then notes pagination, making it efficient and easy to scan.

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

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

Given 12 parameters, no output schema, and read-only annotations, the description does a good job explaining the returned aggregates and pagination. It remains somewhat incomplete because it does not route the agent among the many source-URL analytics siblings or explain the paginated response shape in more detail.

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 schema has 100% parameter description coverage, so the baseline expectation is a 3. The description mentions the analytics window and pagination, but adds no syntax, default, or filtering semantics beyond what the schema already documents for all 12 parameters.

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

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

The description clearly states that the tool returns per-URL citation aggregates, specifically the percentage of analyzed responses citing each URL and the average citation count per response. This is a specific verb/resource description, but it does not distinguish this tool from close siblings such as get-source-url-usage-time-series-tool or list-source-url-prompt-analytics-tool.

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 explicit guidance on when to use this tool versus alternatives, nor does it state prerequisites or exclusions. It only implies that the tool is for aggregate, paginated per-URL analytics rather than time-series or prompt-level breakdowns.

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