Callboard

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

Annotations already declare this as a read-only, idempotent, non-destructive local lookup, so the safety profile is covered. The description adds genuine context by saying what the payload contains (verdict, analysis, and plan-unlocked sections), implying content may be partial depending on the promoter's plan — a non-obvious behavioral detail the annotations don't carry.

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

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

Two tight sentences, with the resource and the id provenance front-loaded and no filler. Every clause carries information the agent needs to select and 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?

For a single-parameter read with annotations and an output schema in place, the description covers what the tool returns and where the id comes from. Minor gaps remain around failure behavior (e.g., unknown or expired id) and its relationship to the lookalike get_brief, but nothing essential 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 0%, so the schema alone leaves 'id' undefined. The description compensates by specifying the id's provenance — it is the identifier returned by a search result — which is exactly the semantics an agent needs to supply a valid value.

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 resource (a single Promoter Brief's full text) and the input source (the id a search result returned), which is far more informative than the bare name 'fetch'. It does not, however, distinguish this from the sibling get_brief, which reads like an overlapping retrieval tool, so sibling differentiation is only partial.

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 clear situational guidance by tying invocation to a preceding search result ('the id a search result returned'), which tells the agent when this is the right call. It stops short of exclusions — there is no statement of when to use get_brief or list_briefs instead.

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, closed-world operation, so the safety profile is covered. The description adds context annotations cannot: the account is scoped to the signed-in promoter and the call functions as a cheap pre-flight check against quota.

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

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

Two sentences, no filler. The return payload is front-loaded and the usage rule follows immediately.

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

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

An output schema exists, so return shape needn't be spelled out, and the description still summarizes the salient fields. The only minor omission is what the tool reports when no plan or allowance exists, but that is likely captured by the output schema.

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

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

The tool takes zero parameters, which is the baseline-4 case, and the description correctly implies no inputs are needed by framing the result as derived from the signed-in session.

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 resource precisely and enumerates exactly what the tool returns: plan tier, Claude access inclusion, and remaining brief allowance. It is clearly distinguishable from data-oriented siblings like get_brief or list_briefs, though it never uses a verb to frame the action.

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 prescribes a calling condition — before run_brief, when the remaining allowance is unknown — and names the sibling tool it gates. An agent knows both when to call it and what it obviates.

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 this as a read-only, idempotent, non-destructive operation. The description adds the meaningful prerequisite that only finished briefs are returned and mentions included content, but it does not detail error behavior or authorization needs; with an output schema present, return-value disclosure is less necessary.

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

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

The description is two tight sentences that front-load the core purpose and then add useful context about content and provenance, with no wasted 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?

For a simple single-parameter read tool with an output schema and rich annotations, the description covers what the tool does, where the id comes from, and what kind of content is returned. Nothing essential 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 0%, so the schema itself does not explain brief_id. The description partially compensates by stating that the id comes from list_briefs or a completed job, but it does not describe the id format or any constraints.

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

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

The description names a specific verb and resource ('finished Promoter Brief by id') and distinguishes it from list_briefs by requiring a known id and returning a single completed brief. It also notes the source of ids, making it clearly different from list_briefs and get_brief_job.

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 tells the agent to use this tool when it has an id from list_briefs or a completed job, which is clear context for invocation. It does not explicitly state when not to use it versus get_brief_job, but the 'finished' qualifier does much of that work.

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

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

Beyond the readOnly, idempotent, non-destructive annotations, the description discloses state-dependent behavior: running returns completed stages and polling guidance, complete returns brief/memo/link, needs_input requires following how_to_continue, and declined has a specific meaning. This is exactly the behavioral context an agent needs for a polling 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?

The description is front-loaded with the tool's purpose, then efficiently covers each relevant state and return behavior. Every sentence carries operational meaning, including the special needs_input and declined cases.

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 polling tool with an output schema and safety annotations already present, the description is largely complete: it covers lifecycle states, polling guidance, and completed-run returns. The remaining gap is that it does not explicitly tie job_id back to run_brief's returned identifier.

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

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

Schema description coverage is 0% for the single required job_id parameter. The description only indirectly implies that job_id identifies a brief started with run_brief; it does not explicitly name job_id or explain where to obtain it, though the single-parameter schema and self-evident name limit the ambiguity.

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 resource and scope: the status of a brief started with run_brief. It also distinguishes this polling/status tool from the initiating sibling run_brief by saying the brief was started with that tool, and it names the lifecycle states the agent will encounter.

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 clear usage context: call this for a job created by run_brief, poll again while running, and retrieve results when complete. It does not explicitly name when not to use it versus siblings like get_brief or list_briefs, but the lifecycle context is strong enough for 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 readOnly, idempotent, closed-world, and non-destructive behavior, so the safety profile is covered. However, the description adds nothing beyond that—no ordering, size limits, pagination, or whether the list is scoped to the authenticated promoter. For a zero-argument list tool, this leaves the agent with no behavioral context at all.

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

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

It is a single short fragment with no wasted words and the scoping detail is front-loaded, but the brevity reflects under-specification rather than discipline—there is only one idea present and it barely exceeds the tool name.

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

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

An output schema exists, so return values need not be described, and there are no parameters to explain. What is still missing is sibling differentiation (why not search_artists) and any hint about scope or emptiness, which matters given how crowded the sibling set is.

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 zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4. No parameter information is missing or contradicted.

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 phrase 'Artists the promoter is watching' conveys the resource being returned, but it is essentially a restatement of the tool name 'Watchlist' rather than a specific verb+resource statement. It does add the scoping detail that entries are per-promoter within Callboard, which helps slightly, but it does not distinguish this from siblings like search_artists or fetch.

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

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

There is no guidance on when to call this versus search_artists or fetch, no mention of prerequisites, and no indication of what an agent should do if the watchlist is empty. Usage must be inferred entirely from the tool name.

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

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

Annotations already declare this as read-only, idempotent, non-destructive, and closed-world. The description adds useful behavior beyond annotations: the listing is newest first, covers the whole team's briefs on Buyer/Company, returns artist/market/verdict/grade/date, and filters case-insensitively. It does not explain limit/pagination behavior, so it is strong but not exhaustive.

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

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

The description is compact and front-loaded: purpose and scope first, returned fields next, filter behavior after that, and the get_brief alternative last. Every clause adds useful information with no repetition of structured fields.

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 rich annotations and an output schema, the description supplies the important call context: scope, ordering, filter semantics, and the full-memo alternative. The main remaining gap is limit/pagination semantics, which keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully describes the artist and market filters, including case-insensitive matching, but it never explains the limit parameter's behavior or bounds. Partial compensation for a three-parameter tool is a 3.

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

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

States a specific verb and resource: listing recent briefs, with explicit scope, ordering, and returned summary fields. It also distinguishes itself from get_brief, which returns the full memo, so an agent can select it without opening another 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 tells the agent when to use this tool for recent summary rows and explicitly routes full-memo needs to get_brief. It also notes optional artist/market filters, making the common selection path 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?

Beyond the annotations (readOnly=false, openWorld=true, idempotent=false), the description discloses runtime (~5 minutes), the billing consequence and the failure exception ('not charged if the run needs more input or fails'), and that it returns a job_id immediately. These are exactly the operational facts an agent needs before spending a paid run.

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?

Dense and front-loaded – purpose and example first, then cost, then async/polling, then flags. Nearly every sentence earns its place, though the force-flag details are packed into one long clause that could be broken out.

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 asynchronous, credit-consuming job tool the description covers the async handoff (job_id + poll cadence), cost and refund behavior, and retry flags; the output schema covers return values and annotations cover the safety profile. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden: it defines the query format with example, and explains both booleans in terms of the situation that triggers them. All three parameters gain meaning not present in the schema.

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

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

States a specific verb and resource ('Start a Promoter Brief') and defines the query shape with a concrete example naming artist, market, and optional venue/date/capacity. An agent can distinguish it from get_brief, get_brief_job, and list_briefs 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?

Explicitly says to poll get_brief_job every 45 seconds, that a run consumes one brief from the monthly allowance, and that force_low_confidence is for previously thin data while force_refresh bypasses the 24-hour cache. These are concrete when-to-use conditions tied to sibling tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior: the result shape (id/title/url) and the empty-query default. Pagination limits or result caps are not mentioned, keeping this at a 3-4 range rather than top marks.

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 is front-loaded, followed by return shape and then the empty-query edge case in descending order of importance.

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 search tool with an output schema and full annotation coverage, the description supplies what the structured fields cannot: result shape, the empty-query fallback, and the fetch follow-up path. Only the relationship to sibling list_briefs/search_artists is unaddressed.

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 single parameter has zero schema description coverage, so the description carries the burden—and it does, explaining that the query matches artist, market, verdict or grade, giving two concrete example queries, and defining the empty-string behavior. Only the matching semantics (substring vs. fuzzy, multi-term handling) remain unspecified.

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 (Search) and resource (Promoter Briefs) with the searchable facets named (artist, market, verdict, grade). The examples and the 'use fetch with a result id' clause make it distinguishable from siblings like list_briefs, search_artists and fetch.

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

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

Explains the follow-up path explicitly (call fetch with a result id to read a brief) and covers the edge case that an empty query returns the most recent briefs. It does not explicitly say when to prefer list_briefs or search_artists instead, so the routing against those siblings is left implicit.

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

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

With annotations already declaring readOnly, idempotent, non-destructive, and closed-world behavior, the description adds useful operational context: 'Free and instant' and 'does not run a brief.' It does not discuss rate limits or authentication, but the annotations cover the main safety profile.

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 compact sentences with the main purpose front-loaded and the disambiguation context parenthetically attached. There is no redundant or wasted 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?

For a simple one-parameter artist lookup with an output schema and rich annotations, the description is largely complete. The main remaining gap is parameter semantics for q, but the usage trigger and safety profile are well covered.

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

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

Schema description coverage is 0%, so the description must carry the burden. It indicates the single parameter q is an artist name query, but it does not clarify whether partial names, exact matches, or fuzzy matching are supported.

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

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

The description gives a specific verb and resource: 'Look up artists by name.' It also distinguishes the tool from run_brief by saying it 'does not run a brief,' but it does not clearly differentiate the tool from the generic sibling 'search.'

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 provides a clear usage trigger: useful when a brief returns needs_input with reason 'disambiguation.' It also implies a boundary by stating it does not run a brief, though it does not name a specific alternative for other search needs.

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