Uphealth Signal

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

Annotations only indicate read/write and destructiveness, so the description adds meaningful behavioral context: synchronous first cue return, federal sourcing, safety checks, non-fabrication guarantee, 422 error conditions, no PHI/BAA in display mode, and the feedback requirement for subsequent cues. It does not contradict the readOnlyHint=false annotation; 'Create' aligns. Could have mentioned idempotency behavior, but schema covers that.

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

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

Four sentences, front-loaded with the core action. Each sentence adds relevant operational or safety context. The last sentence about later cues is somewhat tangential to this specific call, but it usefully frames the sequence of operations. Slightly dense but acceptable given the tool's complexity.

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

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

The tool has 6 parameters, an output schema, and annotations. The description covers the critical invocation aspects: template selection from catalog, required tags/context, error behavior, display mode constraints, and synchronous response. It doesn't need to restate return values because an output schema exists. Minor gaps like idempotency are handled by the schema. Overall complete for a complex create operation.

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 83%, so the baseline is 3. The description adds value by linking template_id to the signal://catalog resource and explicitly tying audience_tags and attributes/patient_context to template prerequisites. This cross-reference helps the agent select and populate parameters correctly. Minor additions beyond schema, but not all parameters (e.g., idempotency_key, feedback_timeout_days) are explained in prose.

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

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

The description opens with a specific verb and resource: 'Create a Signal cued stream for one patient and get the first cue back synchronously.' This precisely defines the tool's action and distinguishes it from sibling tools like get_next_cued_message, which is for subsequent cues. The scope ('one patient') and synchronous return are clear.

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

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

The description gives actionable prerequisites: choose a template_id from the signal://catalog, pre-satisfy audience_tags and patient_context, and notes that clinical templates 422 without them. It also clarifies display mode is the only current option. However, it doesn't explicitly name a sibling alternative for later cues, though the phrase 'Each later cue MUST submit the prior message's feedback' implies a different workflow.

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 (readOnlyHint=false, idempotentHint=true), the description discloses refusal behavior on missing prior feedback, idempotency semantics (same key+same feedback returns cached cue, conflicting feedback returns 409), and content sourcing/processing ('federally-sourced, audience-safety-checked, re-sequenced'). This adds substantial behavioral context not present in annotations.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by the refusal warning and idempotency behavior. It's information-dense but somewhat verbose with parenthetical asides; still, every sentence contributes value.

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 complexity (nested feedback object, output schema), the description covers the essential behavioral contract: submission, refusal, idempotency, and vocabulary source. It doesn't detail the response format, but that's covered by the output schema. Adequate for an agent to 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 schema already describes stream_id and idempotency_key's caching behavior, but the description adds meaning by framing feedback as the patient's response to the prior cue and by referencing the signal://catalog resource for response_action vocabulary. It doesn't elaborate on free_text, but overall it enriches the schema's sparse coverage.

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

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

The description explicitly states the tool submits patient feedback and returns the next cued message, using the verb 'Submit' and identifying the resource as the 'next cued message.' It clearly distinguishes from siblings like create_patient_stream (which starts a stream) and read_stream_state (which reads stream state).

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 clearly states to use this tool when you have feedback from a prior cue and that it refuses without such feedback, returning 409. It also points to the signal://catalog resource for valid response_action vocabulary. However, it doesn't explicitly name alternative sibling tools for other scenarios, though the refusal condition strongly implies when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds substantial context: the data is federally-sourced and audience-safety-checked, the tool does not enumerate messages (corpus stays internal), and it references a catalog for gating contracts. This goes well beyond what annotations 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?

Three sentences, each with a distinct purpose: core function, use case, and exclusions/alternative pointer. No redundancy or unnecessary detail; it is front-loaded with the primary 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?

For a simple zero-parameter, read-only tool with an output schema, the description covers what it returns, when to use it, what it does not return, and where to find more information. It is entirely sufficient 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 zero parameters, and the input schema is empty with additionalProperties=false. Per the rubric, 0 parameters earns a baseline of 4. The description adds no parameter-level details because none exist, which is appropriate.

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

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

The description uses the specific verb 'List' with a clearly defined resource ('curated sandbox topic labels that define the free Discovery corpus'). It distinguishes itself from sibling tools by explicitly stating that it previews content domains before creating a stream, rather than managing streams or messages.

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

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

It states exactly when to use the tool: 'Use it to preview what content domains exist before creating a stream.' It also provides an explicit exclusion ('Does NOT enumerate messages') and directs the user to an alternative resource ('signal://catalog resource') for more comprehensive template and gating information.

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 declare readOnlyHint=true; the description adds 'Free + rate-limited' and 'NO key required', giving context on auth and rate limits beyond the annotation. It doesn't describe error handling or rate-limit behavior, but the added details justify a 4.

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 'Zero setup — NO key required' and the core return details, but the second sentence about signing up for a Discovery key is somewhat promotional and could be trimmed. Still, it's not overly long and every sentence serves some purpose.

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 lookup tool with an output schema, the description covers purpose, usage, auth, rate limits, and source/link return. It doesn't need to explain return values since the output schema exists, making it complete in context.

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 already provides 100% coverage for 'q' with the same examples (e.g., 'high blood pressure', 'sleep'). The description repeats these examples but adds no new parameter meaning, so it fits the baseline for full schema coverage.

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

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

The description states a clear verb+resource: 'Returns ONE already-public federal health fact, list, or tip' with source and link. It distinguishes the lookup from sibling stream/message tools by emphasizing zero setup, no key, and public content.

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 'Zero setup — NO key required' and points to an alternative (Discovery key) for adaptive, patient-specific sequencing. However, it doesn't explicitly state 'when not to use' or name sibling tools, so it's clear but not exhaustive.

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

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

Annotations already state readOnlyHint=true, so the read-only trait is covered. The description adds valuable behavioral context by stating it does not advance the stream or consume a cue, and it mentions event count. It does not discuss auth or rate limits, but given the read-only annotation, this is sufficient.

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 primary function and a clear behavioral caveat. It provides contextual detail ('federally-sourced, audience-safety-checked sequence') without verbosity. Every sentence earns its place.

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

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

The tool is simple with one parameter and an output schema. The description covers the operation scope, when to use it, and what it returns. It is complete enough for an agent to correctly invoke it, especially with the output schema providing return structure.

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

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

Schema coverage is 100% with one parameter, stream_id, well described as 'The stream_id returned by create_patient_stream.' The description does not add extra meaning about the parameter beyond the schema, and it does not mention parameter syntax or formats. It earns the baseline 3 due to full schema coverage.

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

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

The description clearly states the tool reads a stream's current state, current cued message, and event count. It is distinct from siblings like get_next_cued_message (which likely advances) and create_patient_stream (which creates). The explicit phrase 'does NOT advance the stream or consume a cue' further distinguishes its non-mutating behavior.

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

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

The description gives explicit when-to-use guidance: 'between feedback turns to inspect where a patient is.' It also provides a when-not: 'does NOT advance the stream or consume a cue,' implying that advancing tools like get_next_cued_message should be used elsewhere. This is a clear usage directive.

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