signal-bureau

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

With no annotations, the description fully discloses behavioral traits: async default with a ticket, possible synchronous fallback, shared-state caching with fresh:true to bypass, verification semantics (sourceChecked), and limitations (informational only). It also explains keying and rate limits in detail.

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 dense and includes a long tangent about free API key issuance and metering that is not central to using the tool. While informative, it could be more concise; the core usage could be stated more directly.

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 no output schema, the description explains the response shapes (ticket, sync fallback), how to retrieve results (get_answer), caching behavior, and the verdict system. It covers all required operational aspects for a complex 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?

The schema only describes 'fresh' (50% coverage). The description adds meaning to both 'question' (future-focused, tracked coverage) and 'fresh' (forces new synthesis vs. shared cached answer). It does not explicitly define a question format, but this is sufficient for use.

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

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

The description clearly states the tool is for asking about FUTURE or unfolding events, with specific domains (geopolitics, markets, tech, health), and explicitly contrasts with historical facts or general knowledge. This distinguishes it from siblings like get_signals and get_record.

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 explicit when-to-use guidance: 'NOT for historical facts or general knowledge' and recommends 'get_signals/top_accelerating' for browsing what is moving. It also outlines the async workflow, indicating when to use get_answer to collect results.

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 no annotations, the description carries the full burden of behavioral disclosure. It thoroughly describes Stripe-hosted checkout, who completes payment, dryRun semantics (no order recorded, no links, nothing billed), metered billing for 'watch' and 'api' lines, and activation paths for these lines. It also notes that live prices come from /api/tariff and are not hardcoded, adding valuable context beyond the schema.

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

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

The description is long but appropriately sized for the tool's complexity. The first sentence delivers the core purpose, and subsequent sentences efficiently cover dryRun, item catalog, pricing source, and activation paths. Every sentence adds value without redundancy, making it a well-structured, front-loaded explanation.

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 there is no output schema, the description explains what the tool returns ('exact prices plus Stripe checkout links') and the full flow, including dryRun behavior, metering, and desk activation for watch/api lines. It also clarifies that the description deliberately does not state live prices, directing users to /api/tariff. This is complete for a create-order 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?

Although the schema has 100% description coverage, the tool description adds substantial meaning to the 'items' parameter by listing all valid catalog IDs (analyst, power, pilot, desk-private, api, watch) and explaining their meanings and billing details (e.g., the api plan's self-issued key and desk-activated billing). It goes far beyond the schema's generic 'catalog ids above'.

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 opening line, 'Assemble a basket and get exact prices plus Stripe checkout links,' clearly states the tool's purpose: to create an order that returns pricing and checkout links. It distinguishes it from sibling tools like get_quote (which only prices a basket) and get_order (which retrieves existing orders).

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 mentions related tools ('get_quote prices your exact basket first', 'get_account shows the live statement') and explains that watch/api lines have no self-serve checkout, requiring desk activation. However, it does not explicitly state when NOT to use this tool (e.g., 'use get_quote if you only need a price without creating an order'). Thus it provides clear context but lacks explicit 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?

With no annotations, the description carries the full burden and does well: it discloses authentication methods (x-api-key or Bearer sb_live_...), behavior without a key (explains how to get one), privacy stance ('no key, no tracking'), and what data is returned. It implies read-only via 'read surface' and 'statement' but could be more explicit about not modifying anything; it does not mention error handling or rate limits, 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?

The description is concise and front-loaded: it starts with the main output ('Your meter-account statement, live'), then details the contents, followed by authentication requirements and fallback behavior. Each sentence adds essential information without redundancy.

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

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

For a tool with no parameters and no output schema, the description is quite complete: it enumerates the return contents, explains authentication, and covers the no-key case. It lacks explicit return format (e.g., JSON vs text) or possible failure responses, but given the simplicity, it is sufficiently complete for an agent to select and invoke 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?

The tool has 0 parameters and the schema is empty (100% coverage by default). The description adds context about authentication headers (x-api-key, Bearer) which is not in the schema, aiding the agent in constructing the request. Since there are no parameters, the baseline is 4, and the description adds no unnecessary parameter info.

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 identifies the tool as providing a meter-account statement with specific contents: month-to-date metered Reads, tariff, watched topics with billing status, acceptance evidence, and daily cap. It distinguishes from sibling get_* tools by focusing on account/billing-specific data, using the phrase 'your meter-account statement' which is distinct from other tools like get_entity or get_watch_feed.

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

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

The description provides context on when to use the tool: it requires an identified key, and without a key it explains how to get one. It also mentions that read surfaces remain available in free anonymous lanes, giving an alternative access path. However, it does not explicitly compare to sibling tools or state exclusions for specific scenarios, 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?

With no annotations, the description carries full burden and succeeds. It discloses the cost model ('free and unmetered'), the asynchronous status lifecycle, the fact that 'done' includes the complete answer, and the action needed for failures. This is far beyond minimal disclosure.

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

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

The description is compact and front-loaded: the first phrase states exactly what the tool does, and every subsequent clause earns its place by explaining polling behavior, cost, and terminal states. 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 single-parameter tool with no output schema, the description fully explains the integration point (from ask), the response states, the polling interval, the cost implication, and the failure remedy. The agent has everything needed to invoke and interpret the result 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% because the only parameter, ticketId, is already described as 'The uuid the ask tool returned'. The description's reference to 'ticketId (from ask)' adds no new semantic detail beyond what the schema provides, 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?

The description uses a specific verb ('Collect') with a clear resource ('async answer by ticketId'), explicitly ties to the 'ask' tool, and differentiates itself from sibling get_* tools by focusing on asynchronous result retrieval. The status-based outcome states make the purpose unmistakable.

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 explicit conditional guidance: poll after pollAfter seconds when status is 'working', and treat the response as final when status is 'done'. For 'failed' or 'lost', it states the remedy ('asking again'), establishing when to use this tool versus re-submitting via ask.

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 no annotations, the description must carry the burden. It discloses the forward benchmark is contamination-proof and mentions an endpoint for full data, but does not describe return format, pagination, or any potential limitations. This is adequate for a simple read tool but not rich.

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

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

Four concise sentences, each adding value: what it measures, why it's trustworthy, when to use, and where to get the full dataset. No wasted words, though slightly longer than strictly necessary.

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 tool with no parameters and no output schema, the description covers purpose, reliability, usage, and data source. It could be more explicit about return values, but it lists the key metrics and points to a full-data 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?

There are zero parameters, so baseline is 4. The description adds no parameter-specific info, but none is needed since the tool takes no inputs.

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 identifies the tool as a calibration scorecard with specific metrics (Brier score, log loss, skill vs base rate, 95% CIs). It does not use an explicit verb like 'retrieve' or 'get', but the resource is well-defined and distinct from sibling tools focusing on signals, feedback, or entities.

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 explicit when-to-use guidance: 'Use this to decide how much to trust the feed.' It does not mention alternatives or exclusions, but the context is clear for a trust-related assessment 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?

With no annotations, the description discloses ordering ('newest-first'), time window ('up to 14 days'), item fields, keyed authentication ('x-api-key'), behavior for unknown desks, and that payload declares coverage state. It does not explicitly state read-only semantics, but the feed nature strongly implies it.

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 moderately long but each sentence contributes unique information: purpose, roster, delivery, pricing, and coverage state. It is front-loaded with the core function, though the desk list and pricing details add extra length.

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

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

Given the lack of annotations and output schema, the description covers retrieval scope, authentication, differentiation from watch topics, and pricing. It does not detail error cases or exact response envelope, but the mention of 'payload declares its own coverage state' mitigates some uncertainty.

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 already covers both parameters with descriptions and examples. The description adds the full list of valid desk slugs and clarifies the days parameter as a lookback window, enriching the parameter meaning beyond the schema.

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

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

The description clearly states the tool returns a desk's machine feed: 'up to 14 days of the desk's observed items (title, url, source), newest-first'. It also distinguishes itself from sibling tools by explicitly contrasting with 'watch topics' and naming the public desk roster.

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 context for when to use: 'identified delivery is the standard shape for standing feeds' and contrasts with watch topics. It also directs to get_quote for pricing, but does not explicitly state 'use this instead of X' except through the watch topic differentiation.

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?

No annotations are provided, so the description must carry the burden. It discloses the kind of return data (signal count, verticals, why surfacing) but does not state read-only behavior, error handling, or side effects. Adequate for a simple getter but incomplete on safety context.

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

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

A single, front-loaded sentence that efficiently communicates the tool's purpose and key output components 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 single-parameter getter, the description covers what it does and what it returns. Given the large sibling set, adding a note about when not to use it would aid completeness, but the current description is nearly sufficient for selection.

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

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

The input schema only has a bare 'name' string with no description (0% coverage). The description compensates by indicating that the parameter identifies a single entity, adding meaning beyond the schema field.

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 it returns a 'full dossier for one entity' with specific contents: signal count, verticals, and why it's surfacing. This distinguishes it from sibling tools like get_signals or get_record by emphasizing a comprehensive, single-entity view.

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

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

The description implies use when a deep dive on one entity is needed, but it does not explicitly state when to use this tool versus alternatives like search_entities or get_signals. No exclusions or alternative tool names are mentioned.

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 no annotations, the description carries the burden; it details the event structure (entities, market-question count, across-domain mention volume, dates) and optional filters. However, it does not explicitly disclose read-only behavior, return format, or ordering/pagination details beyond the schema's limit parameter.

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

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

The description is two sentences, directly states the core content and the available filter, with no redundant wording. It front-loads the purpose and avoids 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?

No output schema exists, so the description compensates by enumerating what each event includes. It covers the main use case and filter capability, though it could be clearer about the response being a list and any default ordering.

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 already provides 100% coverage for both parameters (limit and query), so the baseline is 3. The description adds that 'query' filters by name or entity, which mirrors the schema and provides no additional syntax or format details.

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 identifies the tool as returning tracked world events, describing them as named arcs with entities and metrics, which distinguishes it from sibling tools like get_entity or get_record. The verb is implied via the tool name 'get', and the scope is well-defined.

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 it should be used to retrieve world events, but does not explicitly contrast it with any of the many sibling get_* tools. It gives context about events being engine-tracked arcs, so an agent can infer when to use it, but no explicit when/where-not guidance is provided.

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

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

With no annotations, the description carries the full burden. It discloses the possible status values, the inclusion of a work-order reference, and the fact that recent reports may still show 'filed'. This provides meaningful behavioral context beyond just saying 'get status'.

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

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

The description is two sentences, front-loaded with the core function, and contains no fluff. It efficiently conveys the status values and a relevant caveat.

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 a single required parameter and no output schema, the description provides the status set, the work-order reference, and a timing nuance. This is sufficient for an AI agent to select and invoke the tool 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?

The schema already describes feedbackId as the value returned by send_feedback (100% coverage). The description adds no new format or syntax details, so it does not improve on 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?

The description clearly states the tool returns the state of a report filed via send_feedback, listing the possible statuses (filed, working, resolved) and mentioning the work-order reference. It distinguishes itself from sibling get_* tools by focusing specifically on feedback status.

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

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

The description implies usage when a feedbackId from send_feedback is available, and provides a temporal caveat about recent reports potentially still reading 'filed'. It does not explicitly name alternatives, but the context is clear given the sibling tools.

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

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

With no annotations, the description carries the full burden. It discloses that the operation is a re-read, specifies the output (basket and honest status), and adds important context about payment truth residing with Stripe. It does not mention side effects, but none are expected for a read operation.

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 wasted words. The first sentence states the core purpose, and the second provides necessary caveats. Information is front-loaded 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?

For a simple read-by-id tool with one parameter and no output schema, the description adequately explains what the tool returns ('recorded basket and its honest status') and provides essential caveats. No additional information seems necessary for an agent 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% and the parameter is documented as 'The UUID returned by create_order'. The description adds no significant new meaning beyond the schema, merely echoing 'created by create_order'. Baseline of 3 applies.

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

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

The description uses a specific verb 're-read' and identifies the resource as 'an order intent created by create_order', which clearly indicates its function. It also distinguishes itself from siblings by stating that payment truth and metered work receipts reside elsewhere.

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

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

The description provides clear context for when this tool is appropriate (reading an order intent) and explicitly notes alternative sources for payment truth (Stripe) and metered work (get_account). However, it does not explicitly state 'use this when you need the basket', relying on inference.

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

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

No annotations are provided, so the description carries full burden. It discloses pricing ($20/topic/month), overlap merging behavior, hold period (30 days), and rate limits (~10 quotes/day per network address). This is rich behavioral context beyond what annotations would typically provide.

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 four sentences and ~130 words, with each sentence adding distinct value (action, pricing, merging, caveats). It is slightly dense but not bloated, and front-loads the primary action with 'Feed in your requirements'.

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 tool with no output schema, the description covers the nature of the result (enumerated quote), pricing, merging logic, hold period, and rate limits. It is complete enough for an agent to invoke the tool confidently, though it could mention potential response format.

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 covers 100% of the single parameter, but the description adds meaning by expanding on 'requirements' with examples (free-form concerns, questions, areas of interest) and explaining the grouping behavior. This enriches the schema description without being redundant.

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

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

The description clearly states the tool converts free-form requirements into an enumerated quote of watched topics with pricing. It uses specific verbs ("feed in", "get back") and resources (requirements, watched topics), distinguishing it from siblings like get_order or get_watch_feed.

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 when you have requirements and want a quote. It clarifies that a quote is not a charge and holds for 30 days, but does not explicitly name alternatives or when-not-to-use scenarios, unlike the high-calibration example.

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 no annotations, the description partially carries the burden by disclosing that the record is 'Appended, never edited,' which indicates append-only immutability. It also mentions the equivalent GET endpoint, but it does not explicitly address side effects, authentication, rate limits, or confirm read-only behavior.

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

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

The description is information-dense but stylistically elaborate, blending precise technical details with narrative context like 'we withdrew in 2026 when re-measurement put it under our own publication bar.' It is not excessively long, but could be streamlined for clarity.

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

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

For a zero-argument tool with no output schema, the description is fairly complete: it lists the major content sections, notes the append-only/immutable nature, and provides the equivalent GET endpoint. It stops short of specifying the exact response format, but the content list and path make the return semantics reasonably clear.

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

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

The input schema is empty, so the baseline is 4. The description reinforces that this is a fixed retrieval of a single record with no parameters needed, and it adds useful context about the exact nature of that fixed object.

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 identifies a specific resource—the correction record—and enumerates its contents (population-level regression, estimate, 95% CI, cohort sizes, window, as-of, and retirement object), making it distinct from sibling tools. However, it is a noun phrase rather than an explicit verb phrase, so the action is inferred from the tool name and the 'GET' reference.

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

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

The description provides context about when this record is relevant (withdrawal of a case-study under the publication bar) and implies retrieval of that correction record. It does not explicitly state when to use this tool versus alternatives like get_calibration or get_truth_object, nor does it provide 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?

With no annotations supplied, the description takes full responsibility for behavioral disclosure. It transparently states this is a read operation ('no model work'), mentions the rate limit, and includes a nuanced statistical caveat that the association is not directional. It also explains the evidenceStatus semantics, adding significant context beyond the schema.

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

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

The description is well-structured and front-loaded with the purpose ('START HERE for browsing'), but the measured property paragraph is lengthy and detailed, arguably going beyond what is needed for tool selection and invocation. Still, it is organized and each part earns its place by providing essential context.

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?

Despite having no output schema and no annotations, the description is remarkably complete for a simple two-parameter read tool. It explains the return payload, the meaning of evidenceStatus, rate limits, and even provides a statistical interpretation caveat. An agent has enough context to select and invoke this tool appropriately.

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

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

Schema coverage is 100%, and the schema descriptions for limit and direction already convey the meaning (default all flagged, filter by trajectory). The tool description adds context about the feed content but does not deepen parameter understanding beyond what the schema provides, so the baseline score 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?

The description clearly states the tool returns the full machine-readable signal feed of entities flagged by the attention engine, with specific fields like trajectory, domains, and evidenceStatus. It differentiates itself from siblings by explicitly positioning as 'START HERE for browsing' and a 'cheap read', making its role distinct.

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

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

The description provides clear context for when to use this tool: start here for browsing, with a low cost of 500/day. It implies this is the first tool to try for signal exploration, but it does not explicitly name alternative tools or exclusions, so it stops 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?

With no annotations, the description carries the full burden. It discloses structural details (layers kept apart and labeled), the honest pending-status behavior for unwired layers, and the free, public nature (no key, no charge). It also mentions the payload equivalence with GET /api/truth/{topic}. Missing failure modes but adequate for a read-only public data 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 heavily padded with a long topic list that duplicates the schema, plus an implementation detail about sb:// and the API endpoint. It is front-loaded with the core purpose, but the redundancy and extra details prevent it from being concise; still structured and organized.

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 tool with no output schema, the description comprehensively explains return layers, topic availability, default, and public access. It also positions the tool relative to get_entity. Minor gaps like explicit error semantics, but overall complete enough for an agent to select and invoke 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 parameter is already fully documented. The description repeats the same topic list and default from the schema without adding new parameter-specific meaning or examples, thus meeting the baseline but not exceeding it.

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 it returns 'the complete public truth object for a topic' and enumerates the object's layers, giving a specific resource and scope. It also distinguishes itself from get_entity by noting it returns the broader live entity dossier, making the purpose 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 identifies the complementary alternative get_entity and implies the use case (public exhibit data) while explicitly listing published topics and the default. However, it does not provide explicit exclusions or when-not-to-use scenarios, limiting it to clear context without full when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does well. It discloses delivery mode (pull), output structure (newest-first items, grading report), and billing behavior (does not gate billing, month refundable). This goes beyond basic read-only/write categorization and provides useful operational context.

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

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

The description is a single long paragraph with the billing policy embedded, which is tangential to tool invocation. While dense with useful information, it lacks front-loading and includes extra commercial details that could be trimmed without losing operational clarity.

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 description adequately covers return contents (observed items with fields, coverage report), ordering, delivery mode, and billing implications. With no output schema, it effectively explains what the tool returns. Minor gaps like error handling or missing-topic behavior keep it from a 5.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds minor context like 'up to 14 days' matching the schema and 'newest-first' which describes output ordering, not parameter meaning. It doesn't meaningfully enrich parameter semantics beyond the schema.

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

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

The description clearly states the tool's function: it delivers a structured daily feed for a machine-watched topic, including up to 14 days of observed items and a coverage-acceptance report. This specific verb+resource (get/feed) distinguishes it from siblings like get_quote and get_desk_feed.

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 explicitly says when NOT to use this tool: 'Topics not yet watched: get_quote prices them.' This provides a clear alternative for unwatched topics and implies this tool is for already-watched topics. Also notes delivery is pull (poll daily or on demand), giving clear usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'No side effects, costs nothing,' which clearly indicates that the tool is safe and free to use. This is significant behavioral information for an agent. It doesn't describe the return format, but no output schema exists, and the description sufficiently covers the non-destructive, no-cost nature.

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 concise and front-loaded, beginning with the key directive 'START HERE' and the metaphor 'the front door.' It efficiently lists the covered topics in a single follow-up sentence and concludes with the safety statement. Every sentence adds value, with no 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?

Given the tool's low complexity (zero parameters, no annotations, no output schema), the description is complete. It explains what the tool does, what information it delivers, and its safety profile. The description fully equips an agent to understand when and why to invoke it.

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

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

The tool has zero parameters, so the schema coverage is trivially complete. Per the rubric, a zero-parameter tool receives a baseline score of 4. The description adds no parameter-specific information, but none is needed since there are no parameters to explain.

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 identifies this tool as the starting point for first contact ('START HERE', 'the front door'), which distinguishes it from sibling tools. It enumerates the specific information it provides (who Signal Bureau is, free/paid content, tariffs, proposing coverage, buying), making its purpose 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 explicitly states when to use the tool: 'START HERE on first contact.' This provides clear context for its role as the entry point. While it doesn't name alternative tools or when not to use it, the 'START HERE' guidance implies that other tools are used after orientation, so the usage context is well defined.

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 no annotations, the description carries the full burden. It transparently describes the workflow: files into a queue, humans review, accepted topics enter provisional lane and appear in signal feed. It also mentions 'Free' and the email purpose. Missing are details on rejection behavior, duplicates, or rate limits, but it covers the core process well.

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

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

The description is two sentences, tightly worded, and front-loaded with the core purpose. Every clause adds value: the net-new scope, the queue outcome, the provisioning lane, the email requirement, and the cost. No filler or redundancy.

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

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

Given the tool's moderate complexity (4 params, no output schema, no annotations), the description sufficiently explains the request lifecycle, including human review and acceptance outcomes. It is missing some edge-case behavior (e.g., duplicate handling, rejection response), but overall an agent can select and invoke this tool with confidence.

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 each parameter has a clear description. The tool description adds slight semantic nuance (e.g., 'topic, entity, or standing question' for the 'topic' field) and explains why email is needed, but most meaning is already captured in 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?

The description clearly states the tool's purpose with a specific verb 'Propose' and a precise resource: 'NET-NEW coverage — a topic, entity, or standing question we don't track yet.' It distinguishes from siblings by emphasizing 'net-new' and the queue/lane workflow, making its unique role obvious.

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

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

The description provides clear context on when to use the tool: when proposing something not yet tracked ('we don't track yet'). It also states a prerequisite ('Needs your human principal's contact email') and a cost signal ('Free'). However, it does not explicitly name alternatives or exclusion cases, though the 'net-new' condition implicitly excludes existing coverage.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the core action without revealing whether the operation is read-only, what it returns (e.g., list or single entity), or any constraints like case sensitivity or partial matching. This lack of transparency could lead to incorrect assumptions.

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

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

The description is a single, well-structured sentence that front-loads the action ('Find') and immediately specifies the resource and method, followed by examples. Every word earns its place; there is no redundancy or unnecessary detail.

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 tool with one parameter and no output schema, the description covers the basic purpose and query format. However, it does not describe the return value (e.g., list of entities, matched fields) or any behavioral edge cases, leaving some uncertainty for the agent about what to expect from the 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?

The input schema only defines a 'query' string with no description, giving 0% schema coverage. The description compensates by explaining that the query can be a name or vertical and provides concrete examples ('iran', 'semiconductors'), adding meaningful semantic context beyond the bare schema.

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

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

The description clearly states the tool's function with a specific verb ('Find'), a resource ('tracked entities/topics'), and a method ('by name or vertical'), complete with examples. It effectively distinguishes itself from sibling tools like get_entity by emphasizing a search across entities/topics rather than retrieval of a specific one.

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

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

The description implies usage for search scenarios (e.g., finding entities by name or vertical) but does not explicitly state when to use it over alternatives like get_entity or propose_topic. There is no exclusionary guidance, so the agent must infer the appropriate context from the action keyword 'search'.

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 no annotations, the description carries the full transparency burden and excels. It discloses rate limits (5/minute, 20/day per network address), the work-order policy for complaints naming real defects, and the response's honesty about durable recording. These are substantive behavioral details beyond the typical mutation description.

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 five dense sentences, each adding distinct information: purpose, constraints, behavioral consequence, ref usage, and response guarantee. It is compact, non-redundant, and front-loaded with the core action.

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 five parameters, no output schema, and no annotations, the description covers purpose, rate limits, side effects, parameter context, and response behavior. The 'honestly' clause partially addresses failure/durability, making the tool's behavior remarkably well-specified.

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 a small clarification for ref ('from your own records') and re-lists the kind values, but these do not meaningfully exceed the schema's existing descriptions for any parameter.

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

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

The description opens with 'File structured feedback with the desk', a specific verb+resource that clearly states the tool's purpose. It enumerates the accepted kinds (bug, improvement, complaint, praise, question) and distinguishes this tool from the sibling get_feedback_status by framing it as the follow-up status tracker.

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

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

The description provides clear when-to-use context: it is for filing structured feedback, with constraints (free, no contact details, rate limits) and ref usage guidance. It explicitly names get_feedback_status for tracking, but it does not address potential overlap with siblings like ask, leaving minor ambiguity for service-related questions.

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 no annotations provided, the description must disclose behavioral traits itself. It explains the content but does not explicitly confirm read-only status, return format, or any special considerations like rate limits or authentication. The reference to the public /today page suggests public accessibility, which is helpful.

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

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

The description is a single, well-structured sentence that front-loads the tool's identity and provides immediate context. No filler or redundancy.

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

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

For a zero-parameter read-only tool with no output schema, the description adequately covers what the tool does and what content it returns. The mention of the public /today page provides a reference point for format. It could be improved by explicitly stating the output format or update frequency.

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

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

The input schema is empty with zero parameters, so there is nothing to describe. The description appropriately focuses on the tool's purpose rather than parameter 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?

The description clearly identifies the tool as providing a daily synthesized narrative, with specific details about cross-domain analysis and 'what to watch'. It distinguishes itself from sibling feeds by referencing the public /today page. However, it lacks an explicit action verb like 'retrieve' or 'get'.

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

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

The description implies this is the go-to tool for a daily overview, but it does not explicitly state when to use it over alternatives such as get_desk_feed or get_watch_feed. No exclusions or alternative tool mentions are provided.

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

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

With no annotations, the description carries the full burden. It explains what is returned, but does not disclose behavioral traits such as data freshness, filtering behavior, potential rate limits, or whether results are dynamic. The phrase 'right now' implies real-time but lacks specifics.

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

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

The description is a single concise sentence that directly conveys the tool's core purpose. There is no redundant or extraneous 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?

The description gives a clear high-level purpose but is somewhat incomplete given no output schema. It does not specify what fields are returned (e.g., names, scores, timestamps), which could be useful for an agent. For a simple list tool, it is adequate but has room for improvement.

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

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

The input schema fully describes the only parameter 'limit' with a clear meaning and default. The description adds no additional parameter context, but the schema coverage is 100%, 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?

The description clearly states the tool returns entities/topics ranked by acceleration and cross-domain attention. It is specific about the resource and ranking, though it lacks an explicit verb like 'list' or 'get', which slightly reduces clarity.

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 is provided on when to use this tool versus alternatives. The sibling tools include other list/search tools, but the description does not mention any conditions or exclusions, leaving the agent to infer usage.

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